Skip to content

System documentation

This documentation describes how Ochema is built and why. It is written for people who evaluate the product, review its security, integrate with it or work on it. To learn how to use the product, read the User guide instead.

The pages follow the arc42 template, one page or group of pages per section. Read in order, they go from the reasons to the details.

# Section The question it answers
1 Introduction and goals What is Ochema, who is it for, and which qualities matter most?
2 Constraints What is fixed before any design choice?
3 Context and scope Who and what is around the system, and where is the line?
4 Solution strategy Which few choices shape everything else?
5 Building blocks Which parts is the system made of, and who depends on whom?
6 Functional architecture: capability map, domain model, lifecycles What does the product do, on which data, through which states?
7 Runtime view How do the parts work together in the flows that define the product?
8 Deployment view: development, the demo environment, production (Proposed) Where does each part run?
9 Cross-cutting concepts, thirteen pages listed below Which mechanisms apply to every module?
10 Quality requirements What is required, how is it met, and what is the evidence?
11 Architecture decisions What was decided, between which options, and at what cost?
12 Risks and known limitations What does the product not do yet, or do with a caveat?
13 Glossary What do the industry terms and the product terms mean?

Section 9 has one page per mechanism, in this order:

  1. Tenant isolation
  2. Authentication and permissions
  3. Sensitive data
  4. Files and vaults
  5. Audit log
  6. Messaging
  7. Background work
  8. API contract
  9. Design system
  10. Internationalization
  11. Archiving
  12. Error handling
  13. Testing

Two reference pages are generated from the code and are never edited by hand: Database tables, from the schema, and API routes, from the OpenAPI document.

Structure diagrams follow the C4 model, in three levels that zoom in:

  1. Context: Ochema as one box, with the people and the outside systems around it. In Context and scope.
  2. Containers: the applications and data stores that run. In Building blocks.
  3. Components: the modules inside the API. Also in Building blocks.

The notation is the same in every structure diagram, and each one repeats its legend.

Shape Meaning
Rounded shape A person, or a group of people with the same role.
Plain box The system, a container or a component, depending on the level. The second line says which, in brackets, with the technology.
Cylinder A data store.
Box with double side borders A system outside Ochema.
Solid arrow A relationship that exists in the code, in the direction of the call or the dependency.
Dashed arrow A relationship that is Planned.
Large box around others A boundary: the system, a machine or a group.

The diagrams use shape and text, not colour, to tell elements apart, so they read the same in the light and the dark theme. Data models use entity relationship diagrams, lifecycles use state diagrams, and flows use sequence diagrams.

These words always mean the same thing, on every page.

Used for Word Meaning
A capability of the product Available It has a screen or a route that works in the product today.
A capability of the product Preview It works, and it belongs to Compliance, whose rules are a regulatory preview until the platform team validates each one.
A capability of the product Planned It is in the scope of the product, and nothing of it runs yet.
A capability of the product Not planned It is in the scope of the product, and it will not be built. The note under it says why.
A compliance rule, retention period or legal text Regulatory preview Shipped with the product and not yet reviewed against the regulation by the platform team.
A compliance rule, retention period or legal text Validated Marked as reviewed by the platform team, with who did it and when.
An integration with an outside system In use The product runs against a real system of this kind today.
An integration with an outside system Simulator The adapter for the real provider is written; the default configuration binds a local stand-in.
An integration with an outside system Planned No adapter exists in the code.
A quality requirement Met Enforced by the code and proven by a test.
A quality requirement Measured A measurement exists, and it is cited.
A quality requirement Target A goal that is not reached yet: what it asks for is not built or not measured. No number is given.
A quality requirement Not verified Built, but not checked under real conditions.
The production environment Proposed The intended design. Nothing of it is provisioned.
An architecture decision Proposed Written and open for review.
An architecture decision Accepted In force, and applied in the code.
An architecture decision Superseded Replaced by a later decision, which the record links to.

Not verified is also used outside the requirement tables, with the same meaning: something is built and was not checked under real conditions, such as sending through a real provider account.

  • Every statement about the behaviour of the product comes from the source code or from running the product with its sample data.
  • A number appears only with its source next to it: a test, a measurement or a file.
  • Paths such as apps/api/src/modules/recruit point into the repository, so a reader with access to the code can check a statement.
  • What does not exist yet is marked Planned, or Target when it is a quality requirement, and is never described as done.