Backend Architecture Diagram

This C4-simplified view keeps the same architecture content while splitting navigation into a runtime flow view and a module map view.

Diagram A: High-level request flow

Read this first to understand how requests move from actors through middleware and layers to external systems.

%%{init: {"flowchart": {"nodeSpacing": 60, "rankSpacing": 70}, "themeVariables": {"fontSize": "17px"}} }%%
flowchart TB
  MA[Mobile App]
  RC[Recruiter curl]

  subgraph API[API Entry]
    API_V1["/api/v1"]
    HEALTH["/health"]
  end

  subgraph MW[Cross-cutting Middleware]
    RL[Rate limiting]
    AM[Auth]
    VZ[Validation]
    EM[Error middleware]
  end

  subgraph P[Presentation Layer]
    PM[Presentation modules]
  end

  subgraph A[Application Layer]
    U[Use-cases]
  end

  subgraph D[Domain Layer]
    DE[Domain entities]
    PORTS[Domain ports]
  end

  subgraph I[Infrastructure Layer]
    REPO[Repositories]
    ADAPTERS[Adapters]
  end

  subgraph X[External Dependencies]
    PG[(PostgreSQL)]
    OAI[OpenAI]
    GOOGLE[Google]
  end

  MA --> API_V1
  MA --> HEALTH
  RC --> API_V1
  RC --> HEALTH

  API_V1 --> RL --> AM --> VZ --> PM
  API_V1 --> RL --> EM
  HEALTH --> RL

  PM --> U
  U --> DE
  U --> PORTS
  PORTS --> REPO
  PORTS --> ADAPTERS

  REPO --> PG
  ADAPTERS --> OAI
  ADAPTERS --> GOOGLE

  EM -. handles failures across modules .-> PM

Diagram B: Presentation modules map

Use this map to zoom in on which presentation modules route into shared application use-cases, stopping at Use-cases.

%%{init: {"flowchart": {"nodeSpacing": 65, "rankSpacing": 75}, "themeVariables": {"fontSize": "17px"}} }%%
flowchart LR
  subgraph P[Presentation Layer]
    AUTH[auth module]
    WALLET[wallet module]
    CATEGORIES[categories module]
    TRANSACTION[transaction module]
    BUDGETS[budgets module]
    DASHBOARD[dashboard module]
    AGENT[agent module]
  end

  subgraph A[Application Layer]
    U[Use-cases]
  end

  AUTH --> U
  WALLET --> U
  CATEGORIES --> U
  TRANSACTION --> U
  BUDGETS --> U
  DASHBOARD --> U
  AGENT --> U

Diagram C — From Use Cases Downward

Use this map to follow architecture flow from Use-cases down through domain and infrastructure to external dependencies.

%%{init: {"flowchart": {"nodeSpacing": 65, "rankSpacing": 75}, "themeVariables": {"fontSize": "17px"}} }%%
flowchart TB
  subgraph A[Application Layer]
    U[Use-cases]
  end

  subgraph D[Domain Layer]
    DE[Domain entities]
    PORTS[Domain ports]
  end

  subgraph I[Infrastructure Layer]
    REPO[Prisma repositories]
    ADAPTERS[Service adapters]
  end

  subgraph X[External Dependencies]
    PG[(PostgreSQL)]
    OAI[OpenAI]
    GOOGLE[Google]
  end

  U --> DE
  U --> PORTS
  PORTS --> REPO
  PORTS --> ADAPTERS
  REPO --> PG
  ADAPTERS --> OAI
  ADAPTERS --> GOOGLE

Domain Map (Business Entities)

Use this view to understand the core business entities and how ownership, membership, and allocation links are modeled.

%%{init: {"flowchart": {"nodeSpacing": 65, "rankSpacing": 75}, "themeVariables": {"fontSize": "17px"}} }%%
flowchart LR
  USER[User]
  WALLET[Wallet]
  CATEGORY[Category]
  TRANSACTION[Transaction]
  BUDGET[Budget]
  BUDGET_MEMBER[BudgetMember]
  BUDGET_ALLOCATION[BudgetAllocation\n- percentage split\n- amount split]

  USER -->|owns| WALLET
  WALLET -->|has categories| CATEGORY
  WALLET -->|has transactions| TRANSACTION

  TRANSACTION -->|belongs to| WALLET
  TRANSACTION -->|belongs to| CATEGORY

  USER -->|owns| BUDGET
  BUDGET -->|has members| BUDGET_MEMBER

  BUDGET -->|has allocations| BUDGET_ALLOCATION
  BUDGET_ALLOCATION -->|links| TRANSACTION
  BUDGET_ALLOCATION -->|assigns split to| BUDGET_MEMBER

• Arrows indicate direction of ownership/reference (for example, Transaction -> Wallet means a transaction belongs to one wallet).
• BudgetAllocation is the join/split entity that connects a transaction to a budget member with either percentage-based or amount-based allocation.

How to read this diagram

• In Diagram A, solid arrows represent the primary request and dependency flow from actors to external systems.
• In Diagram A, the middleware chain is shown explicitly before presentation modules for /api/v1.
• In Diagram A, dashed arrows represent cross-cutting behavior applied across modules.
• In Diagram B, each presentation module converges on shared application Use-cases only.
• In Diagram C, the dependency flow continues from Use-cases to domain, infrastructure, and external dependencies.

Runtime context

• Deployed in the Railway testing environment and exposed via the project custom domain for integration testing.