Overview
The domain vocabulary — scopes, persons, roles, applications, permissions — and the rules that bind them.
Documentation
Everything needed to understand, run, test, and extend the Heimdall API.
Heimdall is a centralized identity management API. It answers one question for many client systems at once — who is this caller, and what are they allowed to do? — while keeping each client system’s identities isolated from every other’s inside its own scope.
The documentation
| Section | What it covers |
|---|---|
| Overview | The domain vocabulary — scopes, persons, roles, applications, Google Users, permissions — and the rules that bind them. |
| Getting started | Prerequisites, environment configuration, migrations, and running the API locally. |
| Architecture | The four layers, the CQRS mediator, the auditing decorator, and the HTTP request pipeline — with class diagrams. |
| Domain model | The entities, their relationships, and the deletion cascade rules — with a class diagram. |
| API reference | Every endpoint, the role that may call it, and the use case it implements. |
| Flows | Sequence diagrams for login, two-factor authentication, Google Sign-In, person onboarding, and audit logging. |
| Operations | Migrations, health checks, logging, rate limiting, and the environment variables the API reads. |
| Environments and deployment | The four environments — local on Docker Desktop, development, homologation and production on the VPS — their env files and their PostgreSQL databases. |
| Requirements | The source specifications: vision, system requirements, use cases, technology stack, testing, workflow, and operations. |
| Changelog | Notable changes in each release — the repository’s CHANGELOG.md, rendered. |
| Contributing | Building from source, the test suites and coverage, migrations, the OpenAPI document, branching and releasing — the repository’s CONTRIBUTING.md, rendered. |
How the documents relate
The requirements documents are the specification — they say what the system must do, and every
feature traces back to a numbered requirement (FR-…, NFR-…) and a use case (UC-…). The other
sections describe what was built and how to work with it, and cite those identifiers wherever a
design decision came from one.
Single source of truth
The requirements pages on this site are the very files under
docs/requirements/
in the
repository — rendered, not copied. Editing the Markdown updates this site.
Getting started
Prerequisites, configuration, migrations, and running the API locally.
Architecture
The four layers, the CQRS mediator, the auditing decorator, and the HTTP request pipeline.
Domain model
The entities, their relationships, and the deletion cascade rules — as class diagrams.
API reference
Every endpoint, the role that may call it, and the use case it implements.
API explorer
Swagger UI over the published OpenAPI document — every endpoint, its schema, and its authorization.
Flows
Sequence diagrams for the paths that are worth tracing end to end.
Environments and deployment
The four environments — local on Docker Desktop, development, homologation and production on one VPS through yggdrasil — and, step by step, what the PostgreSQL behind each has to allow.
Operations
Migrations, start-up guards, health checks, metrics, logging, rate limiting, data retention, and the integrations.
Requirements
The specification: vision, system requirements, use cases, technology stack, data protection, testing, workflow, and operations.
Changelog
Notable changes in each release.
Contributing
Building from source, the test suites and coverage, migrations, the OpenAPI document, branching and releasing.