> For the complete documentation index, see [llms.txt](https://docs.osmosworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.osmosworks.com/overview-and-core-concepts/core-concepts.md). # Core concepts ## What Osmos does Osmos is a multi-tenant backend service that lets organizations offer configurable services to their customers. Each organization gets its own isolated tenant workspace. Within a tenant, administrators define services, staff manage customer requests and applications, and customers submit information and documents through a structured flow. ## Core concepts ### Tenant A tenant is an organization workspace in Osmos. It has a unique slug (used in URLs), a name, a profile (sector, timezone, currency), and settings. The tenant is the top-level boundary for data isolation. Every request to a tenant-scoped endpoint resolves the tenant from the authenticated session or URL and enforces that the caller belongs to that tenant. A tenant is created through the organization onboarding flow. The person who creates the tenant becomes the founding **tenant admin**. ### Principal A principal is a login identity. It holds an email, password hash, and lifecycle timestamps (activated, suspended, removed). Principals can be: * **Tenant admin** — the single administrator who owns the tenant. * **Tenant staff** — team members who are assigned roles and permissions. * **Customer** — a customer who has portal access. * **Platform user** — a user who operates the platform itself, outside any tenant. Tenant admins and staff have profiles in `tenant_members`. Customers with portal access have profiles in `tenant_customers`. Platform users carry their name and role directly on the principal. ### Customer A customer is a person or entity that a tenant serves. A customer record belongs to exactly one tenant. A customer may have portal access (linked to a principal) or may be org-managed only (no login). Org-managed customers are reached through view-only links. ### Party A party is the person or entity a service is about, stored under a customer. For example, a parent (customer) may have two children (parties) for a school admission service. A customer always has at least one self party, which represents the customer themselves. Parties have a flexible `details` JSONB map for custom fields such as date of birth or nationality. ### Service A service is the product a tenant sells or provides. It defines: * A name, description, currency, and party role label (for example, "Applicant" or "Traveller"). * Minimum and maximum parties allowed (optional). * Stages that group the work. * Questions that collect answers. * Requirements (documents) that must be uploaded. * Charges that produce prices or invoices. * Value sets that rules can test membership against. A service is edited as a draft. When it is published, it becomes available for new requests. Archived services are read-only and cannot be edited. ### Stage A stage groups questions, requirements, and charges into one step of a service. A stage can be: * **Ordinary** — collects answers and documents. * **Payment** — requires payment before it can be completed. Stages are ordered. When a request is accepted, the service's stages become the application's stages. ### Question A question is one thing the customer is asked. It has: * A stable `code` unique inside the service. * A label, help text, and hint. * An answer type (text, number, date, single choice, multiple choice, address, and others). * A scope (`REQUEST` or `PARTY`) indicating whether it is asked once for the request or once per party. * Optional options for choice questions. * Optional validation rules. * An optional `showRule` that decides whether the question appears based on earlier answers. ### Requirement (document) A requirement is a document the customer must provide. It has a name, instructions, scope, and a `needRule` that decides whether it is required. Requirements can also require staff review before the application can complete. ### Value set A value set is a named list of values that rules can test membership against. For example, a value set named `ECOWAS` could list member states. Rules use `IN_SET` and `NOT_IN_SET` operators to check answers against value sets. ### Charge A charge is one line item on a service's bill. It has: * A name, amount, and currency (inherited from the service). * A basis: `PER_REQUEST`, `PER_PARTY`, or `PER_QUANTITY`. * An optional `chargeRule` that decides whether the charge applies based on answers. * For `PER_QUANTITY`, a link to a number question that provides the quantity. ### Rule A rule is a condition over answers. It controls whether a stage, question, document, or charge applies. Rules are forward-only: they may only reference questions that come earlier in the flow. Rules can be grouped with `all` (AND), `any` (OR), or `not` (NOT), or be a single condition with an operator and operand. ### Request A request is a customer's draft submission for a service. The customer fills in answers and uploads documents. When ready, the customer submits the request, which moves it to `PENDING`. Staff can then accept or reject the request. ### Application An application is the working record created when staff accept a request. It contains a snapshot of the service at the time of acceptance, so later changes to the service definition do not affect in-flight applications. Applications have stages, answers, documents, an assignee, and a status (`IN_PROGRESS`, `COMPLETED`, or `CLOSED`). ### Invoice and payment An invoice is an amount owed by a customer. Invoices can be created automatically for payment stages or manually by staff. A payment is one checkout attempt against an invoice, processed through Paystack. Successful payments update the invoice and can advance the application past a payment stage. ### Outbox event Outbox events are durable records of work that must be performed outside the current transaction, such as sending emails. They are written to the database and processed by a background scheduler. The scheduler retries failed events with exponential backoff and eventually marks them as completed or failed. ## How concepts connect ```mermaid graph TD Tenant -->|has many| ServiceDefinition Tenant -->|has many| Principal Tenant -->|has many| TenantCustomer Tenant -->|has many| TenantMember Tenant -->|has one| TenantProfile Tenant -->|has one| TenantSettings TenantCustomer -->|has many| Party Party -->|is subject of| ServiceRequest ServiceDefinition -->|defines| ServiceStage ServiceDefinition -->|has many| ServiceQuestion ServiceDefinition -->|has many| ServiceRequirement ServiceDefinition -->|has many| ServiceCharge ServiceDefinition -->|has many| ServiceValueSet ServiceStage -->|contains| ServiceQuestion ServiceStage -->|contains| ServiceRequirement ServiceStage -->|contains| ServiceCharge ServiceRequest -->|submitted for| ServiceDefinition ServiceRequest -->|created by| TenantCustomer ServiceRequest -->|about| Party ServiceRequest -->|accepted becomes| Application Application -->|copies| ServiceStage[ApplicationStage] Application -->|has| ApplicationQuestion Application -->|has| ApplicationRequirement Application -->|has| ApplicationAnswer Application -->|has| ApplicationDocument Application -->|may have| Invoice Invoice -->|paid by| Payment ``` ## Actor types * **Platform administrator** — manages tenants and billing plans through platform endpoints. * **Tenant administrator** — configures the tenant, services, roles, and landing page; can perform any tenant-scoped action. * **Tenant staff** — has a role with a set of permissions. Can review requests, manage applications, and perform other allowed operations. * **Customer** — submits requests and edits their own applications within the current stage. ## Typical backend flow 1. A platform administrator or onboarding flow creates a tenant. 2. The tenant admin defines a service with stages, questions, requirements, charges, and rules. 3. The tenant admin publishes the service. 4. A customer creates a draft request, answers questions, and uploads documents. 5. The customer submits the request. 6. Staff review the request and accept or reject it. 7. On acceptance, an application is created from the service snapshot. 8. The customer and staff complete application stages, which may include payment. 9. When all stages are complete, the application is marked `COMPLETED`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.osmosworks.com/overview-and-core-concepts/core-concepts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.