Software Architecture
Show us the layers in your system and your domain classes. You can also include individual class diagrams in your stories on GitHub
Put in your highlevel arch diagram (ie the major components)
For all existing arch diagrams, please only describe changes in your arch
The big picture structure in the diagram and the folder layout in the project sort of go hand-in-hand as they both follow a pretty modular setup where stuff is grouped by purpose: data, logic, and how everything gets shown to the user. The diagram itself kind of maps out how the different parts of the system connect on a conceptual level like users, claims, flights, documents, that kind of thing. And then the actual directory structure shows how that idea turns into real code.
So for instance, the entities you see in the diagram show up as actual database models in backend/src/db/schema.ts, and those are built using Drizzle ORM. Meanwhile, there's a services/ folder (specifically under backend/src/services/ ) that kind of matches the logic you’d expect from how those entities relate. You've got files like delayService.ts or submittedClaimService.ts that, in a way, are doing the actual behind-the-scenes work, like matching a user with their claim, pulling in flight info, or keeping track of who submitted what. It’s all pretty directly tied to what’s in the ERD.
The routes in backend/src/routes/ kind of act like the outward-facing part. These routes turn that internal model into something the frontend or automations can actually use. Now, going further than what the diagram covers, the backend has extra bits like emails/ and jobs/, which kind of match up with the AI and OCR parts you see mentioned in the diagram. These are handling automation, pulling info out of documents, and doing things that go beyond just basic create-read-update-delete type stuff. The frontend lives in its own folder, frontend/, and even though the diagram doesn’t really show this part, it’s definitely a key piece. This is where all the screens and interfaces come from built with React Native and Expo so users can actually interact with everything that’s going on in the backend.
Something the diagram skips, which the directory includes, is all the stuff that makes the codebase work in practice like testing (in test/), config files (tsconfig.json, eslint.config.mts), and setup files for containers and deployment (docker-compose.yml). There’s also an n8n/ folder, which is where those automation workflows live these run on top of the system and handle things like connecting services or triggering actions based on logic from the rest of the app.
The diagram and the folder structure are definitely in sync. The diagram shows what kinds of data exist and how they connect, while the folder layout shows how all of that actually works in code. The top folders frontend/, backend/, n8n/ line up with the major parts of the system, and then everything inside fills in the rest of the picture that the diagram only hints at.
| Architectural Layer | Example in Diagram (ERD) | Implementation in Code | Description |
|---|---|---|---|
| Core Entities / Database | User, Claim, Flight, Documents | backend/src/db/schema.ts |
Tables in the ERD are represented as Drizzle ORM models. |
| Relationships / Domain Logic | Foreign keys (e.g., Claim → User, Claim → Flight) | backend/src/services/ |
Services implement logic connecting database entities. |
| API Layer (Controllers) | (Not shown in ERD) | backend/src/routes/ |
REST endpoints exposing backend functionality. |
| Automation / AI Integrations | AI-Agent, OCR_result |
backend/src/emails/, backend/src/jobs/
|
Automated claim handling, OCR, and background jobs. |
| Frontend / Presentation | (Not represented in ERD) | frontend/ |
React Native interface for user interaction. |
| Testing / Validation | (Not represented in ERD) |
backend/src/test/, frontend/__tests__/
|
Unit and integration testing layers. |
| Configuration / Infrastructure | (Not represented in ERD) |
docker-compose.yml, tsconfig.json, eslint.config.mts
|
Build, lint, and deployment configuration. |
| Workflow Automation | (Implicit support layer) | n8n/ |
Workflow orchestration and process automation. |
