System Overview
IPFOS is a polyglot microservices platform: independent services, each owning its own PostgreSQL database, fronted by a single Traefik gateway, communicating over REST and RabbitMQ.
Core principles
- One database per service, no cross-service foreign keys. Services reference each other's entities only by canonical UUIDs (
userId,departmentId,projectId). - One public ingress. Only Traefik publishes an API port (
8080). Service and database ports stay internal to the compose network. - Synchronous HTTP is the default for service-to-service needs; RabbitMQ RPC is allowed only for the approved department/project/PMO lookup path.
- Events are fire-and-forget on a durable topic exchange (
os.events); consumers are idempotent viaeventId. - JWT everywhere. The auth service issues platform JWTs; each service enforces auth and permissions itself. (Gateway-level JWT validation is planned but not yet wired into Traefik.)
Bounded contexts
| Context | Owns | Lives in |
|---|---|---|
| Auth | admin accounts, external identities, refresh tokens, auth audit | os-auth-service |
| Users (logical) | users, roles/permissions, departments + memberships, projects, badges, invitations | co-hosted in os-auth-service in v1, with internal separation preserved for later extraction |
| Tickets | tickets, participants, comments, attachments, SLA policies, action timeline | os-tickets-service |
| Notifications | in-app notifications | os-integration-service |
| Meals | meal library, weekly menus, selections | os-meals-service (designed; domain code still minimal) |
Where the truth lives
- Architecture and design decisions:
os-backend/docs/design/—architecture-proposal.md,solution-design.md,data-model.md. - API contract:
os-backend/docs/design/api-spec.yml— the hand-maintained OpenAPI 3.0.3 spec. This is what the API Reference section of this site is generated from, and it is the source of truth when frontend and backend disagree on a data shape. - Runtime routing/ports:
os-backend/compose.ymlandos-backend/traefik/dynamic.yml. Note thatdocs/design/gateway-and-ports.mdpredates implementation and lists a stale port for the integration service (8084 vs. the actual 8087) — compose and Traefik config are authoritative.