Software Architecture

System Architecture Diagram

Link to Eraser Board

11-19-2025

03-22-2026

04-13-2026

Database ER Diagram

Link to Lucide Chart Diagram

Domain Diagram

Connection between Project Directory Structure and System Architecture

The project follows a modular folder structure that closely aligns with the system's conceptual Entity Relationship Diagram (ERD). Components are grouped by purpose—data, logic, and presentation—translating the architectural concepts into concrete code.

1. Backend (Data & Logic)

The backend structure mirrors the relationships defined in the diagram:

• Entities & Database: The entities shown in the diagram (Users, Claims, Flights) are implemented as database models in backend/src/db/schema.ts using Drizzle ORM.
• Business Logic: The backend/src/services/ directory contains the specific logic for how these entities interact. Files like delayService.ts and submittedClaimService.ts handle the behind-the-scenes work—matching users to claims and processing flight data—directly implementing the relationships found in the ERD.
• API Routes: The backend/src/routes/ directory acts as the interface, exposing internal models to the frontend and automation services.

2. Automation & AI

While the diagram references AI Agents and OCR results, the implementation lives in specific backend sub-modules:

• backend/src/emails/ & backend/src/jobs/: These directories handle background automation, document parsing, and communication tasks.

3. Frontend

• frontend/: Built with React Native and Expo, this directory contains the user interface. While the ERD focuses on data, this folder provides the screens required for users to interact with the backend logic.

4. Infrastructure & Tooling

Several essential components exist in the code structure to support the application, even if they are not visualized in the high-level diagram:

• Testing: Unit and integration tests reside in backend/src/test/.
• Workflows: The n8n/ folder contains workflow orchestration logic that sits on top of the system to connect services.
• Configuration: Deployment and environment setups are managed via docker-compose.yml, tsconfig.json, and eslint.config.mts.

Architectural Mapping

The following table maps the high-level architectural layers to their specific implementation within the codebase.

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)	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	Build, lint, and deployment configuration.
Workflow Automation	(Implicit support layer)	n8n/	Workflow orchestration and process automation.