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.
How it is organized
Section titled “How it is organized”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? |
Cross-cutting concepts
Section titled “Cross-cutting concepts”Section 9 has one page per mechanism, in this order:
- Tenant isolation
- Authentication and permissions
- Sensitive data
- Files and vaults
- Audit log
- Messaging
- Background work
- API contract
- Design system
- Internationalization
- Archiving
- Error handling
- 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.
Where to start
Section titled “Where to start”- To evaluate the product: sections 1 and 3, then the capability map and section 12.
- To review security and privacy: section 3, then Tenant isolation, Authentication and permissions, Sensitive data and section 10.
- To integrate with Ochema: section 3, then the API contract and the API routes.
- To work on the code: sections 4 and 5, then the concept pages of the area you will touch and the decisions they link to.
How to read the diagrams
Section titled “How to read the diagrams”Structure diagrams follow the C4 model, in three levels that zoom in:
- Context: Ochema as one box, with the people and the outside systems around it. In Context and scope.
- Containers: the applications and data stores that run. In Building blocks.
- 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.
The words for the state of things
Section titled “The words for the state of things”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.
How statements are sourced
Section titled “How statements are sourced”- 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/recruitpoint 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.