Skip to main content

Architecture Orientation

A reading order for your first few days, before diving into a real task. Each link is an existing doc — this page is the tour guide, not a duplicate of their content.

Day 1 — the shape of the system​

  1. Build & Run — what Eos is, the stack, the monorepo layout.
  2. Architecture Overview — modular monolith, the Api/Application/Domain/Infrastructure/Workers layering, why Domain is thin, module boundaries, API versioning.
  3. Authorization Model — every controller action goes through one of the authorization mechanisms described here; you'll hit this on your first endpoint whether you're touching it directly or not.

Day 2 — how a typical feature is actually built​

Most new backend work is a variation on the Reference CRUD pattern — read these in order, they build on each other:

  1. Reference CRUD — the shape every new reference entity (Cities, Countries, Branches, ...) follows end-to-end.
  2. Territory Access — how row-level access gating works, layered on top of the CRUD pattern.
  3. Pagination — server-side pagination is the standard, both backend and frontend halves.
  4. Translatable Labels — per-Branch/Client/ Language label overrides used across the UI.

Skim the rest of patterns/ (attachments, audit-trail, automation-engine, delete-semantics, eventing, fluent-validation) when you actually touch that area — they're reference material, not a required read up front.

Day 3 — frontend, then the API surface​

  1. Frontend Design System — the vendored CSS system (tokens.css/app.css), why it's not antd, and the shared component kit. frontend/src/eos-web/CLAUDE.md has the full detail this page summarizes.
  2. API Reference — browse a couple of endpoints you'll actually be calling; it's auto-generated from the real OpenAPI spec, so it's always current.

Making your first change​

A good first task is a small addition to an existing Reference CRUD entity (a new field, a new lookup) rather than a new module — it touches every layer described above in miniature without requiring a new pattern decision. Ask your lead to point you at a currently-open S-effort item in TASKS.md if one isn't already assigned.

Where things live day-to-day​

  • CLAUDE.md (root, backend/, frontend/src/eos-web/) — current-state rules; if this site ever looks out of date, those files win.
  • DEVLOG.md — historical build narrative, not current rules — read it when you want the story of why, not what to do now.
  • TASKS.md — open work, by priority tier. docs-internal/planning/task-details.md has the full write-up behind any task's one-line summary.
  • docs-internal/ — internal design docs, migration plans, audits, runbooks — not published here, browse the folder directly.

What this tour deliberately skips​

Deployment/provisioning (Key Vault, multi-client rollout, CI/CD) isn't part of a new engineer's first days — see Client Onboarding when you actually need it.