# spliit-app/spliit architecture

> Architecture diagram of the GitHub repository spliit-app/spliit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spliit-app/spliit
- Repository: https://github.com/spliit-app/spliit

## Overview

1. **Overall shape**
   - Spliit is a **Next.js App Router** application centered on a shared-expenses domain.
   - The app is split into:
     - **UI pages/components** under `src/app`
     - **API/backend logic** under `src/app/api` and `src/trpc`
     - **Persistence** via **Prisma** in `prisma/` against a **PostgreSQL** database
     - **Optional external integrations** for S3 uploads and OpenAI-based receipt/category extraction

2. **Primary domain boundary: groups**
   - Nearly all user-facing features hang off a **group**.
   - The main route area is `src/app/groups/[groupId]`, which contains:
     - expenses
     - balances/reimbursements
     - activity log
     - group information/settings
     - stats
   - This makes the group the central aggregate for both UI navigation and backend queries.

3. **Client/server split**
   - The app uses Next.js server components and client components side by side.
   - Pages like `page.tsx` often act as server entry points that fetch or prepare data, while `page.client.tsx` and many reusable widgets handle interaction-heavy UI.
   - This is important for diagramming because data access and rendering are not purely client-side; many views are assembled on the server and hydrated with client controls.

4. **Backend API layer**
   - The main application API is implemented with **tRPC** under `src/trpc`.
   - `src/trpc/routers/_app.ts` composes feature routers for:
     - groups
     - expenses
     - balances
     - activities
     - categories
   - This creates a typed RPC boundary between UI and domain logic, rather than a traditional REST-first app.

5. **tRPC feature decomposition**
   - The backend is organized by feature procedures:
     - group create/get/update/list/details
     - expense create/get/update/delete/list
     - balances and reimbursement calculations
     - activity listing
     - category listing
     - group stats
   - These procedures are the main application service layer and are likely where Prisma queries, validation, and business rules live.

6. **Database and schema**
   - **Prisma** is the persistence layer, with schema in `prisma/schema.prisma` and a long migration history showing domain evolution.
   - The migrations indicate core entities and concerns such as:
     - groups, expenses, shares, categories
     - reimbursement expenses
     - timestamps and cascading deletes
     - document URLs and document metadata
     - activity log
     - recurring expenses
     - group currency and currency conversion
   - The database is not just storage; it encodes the accounting model that drives balances and stats.

7. **Core business flows**
   - The central user flow is:
     1. create or join a group
     2. add expenses with participants and split mode
     3. compute balances and reimbursements
     4. inspect activity/history and stats
   - Helpers in `src/lib/balances.ts`, `src/lib/totals.ts`, and `src/lib/currency.ts` suggest that calculations are mostly server-side, with the UI rendering derived financial summaries.

8. **Expense documents and receipt scanning**
   - There is an optional document-upload subsystem under `src/app/api/s3-upload` and expense UI components related to documents.
   - Files are uploaded to **S3-compatible storage**, and the app stores references/metadata in the database.
   - A second optional flow uses **OpenAI Vision** to extract expense data from receipts. This depends on the upload/document path because the receipt image must first be stored and exposed.

9. **Export and integration endpoints**
   - Expenses can be exported via dedicated routes:
     - CSV export
     - JSON export
   - These are separate route handlers, so exports are server-generated data extracts rather than client-side transformations.
   - The app also includes a health API surface at `/api/health`, with readiness and liveness checks for deployment/runtime monitoring.

10. **Internationalization**
   - The `messages/` directory contains localized strings for many languages.
   - `src/i18n/request.ts` and `src/lib/locale.ts` indicate locale resolution and message loading are first-class concerns.
   - For architecture diagrams, this is a cross-cutting layer affecting nearly all pages, not a standalone subsystem.

11. **UI and design system**
   - `src/components/ui` contains a **shadcn/ui-style component library** built on top of Tailwind CSS.
   - Reusable domain components like `group-form`, `expense-form`, `currency-selector`, and `locale-switcher` sit above the generic UI layer.
   - The UI architecture is component-driven, with domain forms and lists composing shared primitives.

12. **Operational/runtime concerns**
   - The repo is prepared for multiple deployment modes:
     - Vercel-hosted production
     - local development with PostgreSQL
     - Docker/containerized deployment
   - Supporting files include `Dockerfile`, `compose.yaml`, `.devcontainer`, and scripts for local DB startup and container entrypoints.
   - This means the diagram should include both the app runtime and its database/runtime dependencies, not just browser-to-server traffic.

13. **Cross-cutting support code**
   - `src/lib` contains shared infrastructure such as:
     - environment parsing
     - feature flags
     - Prisma client setup
     - schema validation
     - health checks
     - utility helpers
   - `src/scripts` and `scripts/` contain build/migration/container helpers, which support deployment and maintenance rather than request handling.

14. **What to emphasize in a diagram**
   - The most important edges are:
     - browser/UI → Next.js pages/components
     - pages/components → tRPC procedures / route handlers
     - tRPC/handlers → Prisma → PostgreSQL
     - upload/receipt features → S3/OpenAI
     - health/export routes as separate server entry points
   - The whole system is organized around **group-scoped expense accounting**, with optional external services extending the core workflow.

Main entry points: [`prisma/schema.prisma`](https://github.com/spliit-app/spliit/blob/main/prisma/schema.prisma) (Prisma schema), [`src/trpc/routers/_app.ts`](https://github.com/spliit-app/spliit/blob/main/src/trpc/routers/_app.ts) (App router), [`src/lib`](https://github.com/spliit-app/spliit/tree/main/src/lib) (Accounting logic), [`compose.yaml`](https://github.com/spliit-app/spliit/blob/main/compose.yaml) (Ops runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["Next.js app"]
  node_node_home["Home<br/>route entry<br/>[page.tsx]"]
  node_node_groups["Groups area<br/>app section"]
  node_node_group_pages["Group pages<br/>server/client pages"]
  node_node_expense_export["Exports<br/>route handlers"]
end

subgraph group_grp_trpc["tRPC API"]
  node_node_trpc_api["tRPC endpoint<br/>api route<br/>[route.ts]"]
  node_node_trpc_app["App router<br/>tRPC composition<br/>[_app.ts]"]
  node_node_trpc_groups["Groups RPC<br/>feature router"]
  node_node_trpc_expenses["Expenses RPC<br/>feature router"]
  node_node_trpc_balances["Balances RPC<br/>feature router"]
  node_node_trpc_activity["Activity RPC<br/>feature router"]
  node_node_trpc_categories["Categories RPC<br/>feature router"]
end

subgraph group_grp_data["Persistence"]
  node_node_prisma[("Prisma schema<br/>data model<br/>[schema.prisma]")]
  node_node_postgres[("PostgreSQL<br/>database")]
end

subgraph group_grp_shared["Shared libs"]
  node_node_business["Accounting logic<br/>domain logic"]
  node_node_i18n["Locale loading<br/>i18n<br/>[request.ts]"]
end

subgraph group_grp_ui["UI system"]
  node_node_ui_primitives["UI primitives<br/>design system"]
  node_node_domain_ui["Domain UI<br/>feature components"]
end

subgraph group_grp_infra["Runtime & integrations"]
  node_node_health["Health API<br/>route handlers"]
  node_node_upload["S3 upload<br/>route handler<br/>[route.ts]"]
  node_node_integrations["Ops runtime<br/>deployment<br/>[compose.yaml]"]
end

node_node_home -->|"navigates to"| node_node_groups
node_node_groups -->|"renders"| node_node_group_pages
node_node_group_pages -->|"queries/mutates"| node_node_trpc_api
node_node_expense_export -->|"reads data"| node_node_trpc_expenses
node_node_health -->|"checks"| node_node_business
node_node_upload -->|"stores metadata"| node_node_prisma
node_node_trpc_api -->|"dispatches to"| node_node_trpc_app
node_node_trpc_app -->|"includes"| node_node_trpc_groups
node_node_trpc_app -->|"includes"| node_node_trpc_expenses
node_node_trpc_app -->|"includes"| node_node_trpc_balances
node_node_trpc_app -->|"includes"| node_node_trpc_activity
node_node_trpc_app -->|"includes"| node_node_trpc_categories
node_node_trpc_groups -->|"reads/writes"| node_node_prisma
node_node_trpc_expenses -->|"reads/writes"| node_node_prisma
node_node_trpc_balances -->|"calculates"| node_node_business
node_node_trpc_activity -->|"reads"| node_node_prisma
node_node_trpc_categories -->|"reads"| node_node_prisma
node_node_business -->|"supports"| node_node_prisma
node_node_business -->|"localizes"| node_node_i18n
node_node_prisma -->|"persists to"| node_node_postgres
node_node_domain_ui -->|"composes"| node_node_ui_primitives
node_node_group_pages -->|"uses"| node_node_domain_ui
node_node_domain_ui -->|"displays"| node_node_i18n
node_node_integrations -->|"runs with"| node_node_postgres
node_node_integrations -->|"deploys"| node_node_trpc_api
node_node_integrations -->|"supports"| node_node_upload

click node_node_home "https://github.com/spliit-app/spliit/blob/main/src/app/page.tsx"
click node_node_groups "https://github.com/spliit-app/spliit/tree/main/src/app/groups/[groupId]"
click node_node_group_pages "https://github.com/spliit-app/spliit/tree/main/src/app/groups/[groupId]"
click node_node_expense_export "https://github.com/spliit-app/spliit/tree/main/src/app/groups/[groupId]/expenses/export"
click node_node_health "https://github.com/spliit-app/spliit/tree/main/src/app/api/health"
click node_node_upload "https://github.com/spliit-app/spliit/blob/main/src/app/api/s3-upload/route.ts"
click node_node_trpc_api "https://github.com/spliit-app/spliit/blob/main/src/app/api/trpc/[trpc]/route.ts"
click node_node_trpc_app "https://github.com/spliit-app/spliit/blob/main/src/trpc/routers/_app.ts"
click node_node_trpc_groups "https://github.com/spliit-app/spliit/tree/main/src/trpc/routers/groups"
click node_node_trpc_expenses "https://github.com/spliit-app/spliit/tree/main/src/trpc/routers/groups/expenses"
click node_node_trpc_balances "https://github.com/spliit-app/spliit/tree/main/src/trpc/routers/groups/balances"
click node_node_trpc_activity "https://github.com/spliit-app/spliit/tree/main/src/trpc/routers/groups/activities"
click node_node_trpc_categories "https://github.com/spliit-app/spliit/tree/main/src/trpc/routers/categories"
click node_node_prisma "https://github.com/spliit-app/spliit/blob/main/prisma/schema.prisma"
click node_node_business "https://github.com/spliit-app/spliit/tree/main/src/lib"
click node_node_i18n "https://github.com/spliit-app/spliit/blob/main/src/i18n/request.ts"
click node_node_ui_primitives "https://github.com/spliit-app/spliit/tree/main/src/components/ui"
click node_node_domain_ui "https://github.com/spliit-app/spliit/tree/main/src/components"
click node_node_integrations "https://github.com/spliit-app/spliit/blob/main/compose.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_home,node_node_groups,node_node_group_pages,node_node_expense_export toneBlue
class node_node_trpc_api,node_node_trpc_app,node_node_trpc_groups,node_node_trpc_expenses,node_node_trpc_balances,node_node_trpc_activity,node_node_trpc_categories toneAmber
class node_node_prisma,node_node_postgres toneMint
class node_node_business,node_node_i18n toneRose
class node_node_ui_primitives,node_node_domain_ui toneIndigo
class node_node_health,node_node_upload,node_node_integrations toneTeal
```

## Components

### Next.js app

App Router pages, layouts, and route handlers for the user-facing product.

- [Home](https://github.com/spliit-app/spliit/blob/main/src/app/page.tsx): route entry · Landing and top-level navigation entry point. · `src/app/page.tsx`
- [Groups area](https://github.com/spliit-app/spliit/tree/main/src/app/groups/[groupId]): app section · Primary group-scoped UI shell and pages. · `src/app/groups/[groupId]`
- [Group pages](https://github.com/spliit-app/spliit/tree/main/src/app/groups/[groupId]): server/client pages · Expenses, balances, activity, info, stats, and edit views assembled from server and client components. · `src/app/groups/[groupId]`
- [Exports](https://github.com/spliit-app/spliit/tree/main/src/app/groups/[groupId]/expenses/export): route handlers · Server-generated CSV and JSON expense export endpoints. · `src/app/groups/[groupId]/expenses/export`

### tRPC API

Typed application service layer for groups, expenses, balances, activity, and categories.

- [tRPC endpoint](https://github.com/spliit-app/spliit/blob/main/src/app/api/trpc/[trpc]/route.ts): api route · HTTP bridge exposing the typed RPC API. · `src/app/api/trpc/[trpc]/route.ts`
- [App router](https://github.com/spliit-app/spliit/blob/main/src/trpc/routers/_app.ts): tRPC composition · Composes feature routers into the application RPC surface. · `src/trpc/routers/_app.ts`
- [Groups RPC](https://github.com/spliit-app/spliit/tree/main/src/trpc/routers/groups): feature router · Group create, get, update, list, details, and stats procedures. · `src/trpc/routers/groups`
- [Expenses RPC](https://github.com/spliit-app/spliit/tree/main/src/trpc/routers/groups/expenses): feature router · Expense CRUD and listing procedures. · `src/trpc/routers/groups/expenses`
- [Balances RPC](https://github.com/spliit-app/spliit/tree/main/src/trpc/routers/groups/balances): feature router · Balance and reimbursement calculations. · `src/trpc/routers/groups/balances`
- [Activity RPC](https://github.com/spliit-app/spliit/tree/main/src/trpc/routers/groups/activities): feature router · Activity listing procedures. · `src/trpc/routers/groups/activities`
- [Categories RPC](https://github.com/spliit-app/spliit/tree/main/src/trpc/routers/categories): feature router · Category listing procedures. · `src/trpc/routers/categories`

### Persistence

Prisma schema, migrations, and PostgreSQL-backed data model.

- [Prisma schema](https://github.com/spliit-app/spliit/blob/main/prisma/schema.prisma): data model · Domain schema and migrations for groups, expenses, shares, categories, documents, activity, recurrence, and currency. · `prisma/schema.prisma`
- **PostgreSQL**: database · Primary relational datastore.

### Shared libs

Cross-cutting business logic, validation, locale, and infrastructure helpers.

- [Accounting logic](https://github.com/spliit-app/spliit/tree/main/src/lib): domain logic · Balances, totals, currency, validation, and health helpers. · `src/lib`
- [Locale loading](https://github.com/spliit-app/spliit/blob/main/src/i18n/request.ts): i18n · Locale resolution and message loading for the UI. · `src/i18n/request.ts`

### UI system

Reusable domain components and base design-system primitives.

- [UI primitives](https://github.com/spliit-app/spliit/tree/main/src/components/ui): design system · Reusable shadcn-style components built on Tailwind. · `src/components/ui`
- [Domain UI](https://github.com/spliit-app/spliit/tree/main/src/components): feature components · Group forms, expense forms, selectors, lists, and widgets. · `src/components`

### Runtime & integrations

External services and deployment/runtime entry points.

- [Health API](https://github.com/spliit-app/spliit/tree/main/src/app/api/health): route handlers · Readiness and liveness probes for deployment monitoring. · `src/app/api/health`
- [S3 upload](https://github.com/spliit-app/spliit/blob/main/src/app/api/s3-upload/route.ts): route handler · Upload endpoint for receipt and document storage. · `src/app/api/s3-upload/route.ts`
- [Ops runtime](https://github.com/spliit-app/spliit/blob/main/compose.yaml): deployment · Docker, devcontainer, scripts, and environment setup for local and containerized runs. · `compose.yaml`

## Connections

- Home → Groups area: navigates to · Top-level app entry routes into group-centric flows.
- Groups area → Group pages: renders · Group shell hosts the main group pages and nested views.
- Group pages → tRPC endpoint: queries/mutates · Pages and client components call the typed RPC surface.
- Exports → Expenses RPC: reads data · Exports are built from expense domain data.
- Health API → Accounting logic: checks · Health endpoints depend on shared health/runtime helpers.
- S3 upload → Prisma schema: stores metadata · Uploads are persisted as document references and related expense data.
- tRPC endpoint → App router: dispatches to · Single API route delegates to the composed router.
- App router → Groups RPC: includes · Groups feature router is part of the app RPC surface.
- App router → Expenses RPC: includes · Expenses feature router is part of the app RPC surface.
- App router → Balances RPC: includes · Balances feature router is part of the app RPC surface.
- App router → Activity RPC: includes · Activity feature router is part of the app RPC surface.
- App router → Categories RPC: includes · Categories feature router is part of the app RPC surface.
- Groups RPC → Prisma schema: reads/writes · Group procedures persist and load group-scoped records.
- Expenses RPC → Prisma schema: reads/writes · Expense procedures persist expense, share, and document data.
- Balances RPC → Accounting logic: calculates · Balances rely on shared accounting logic.
- Activity RPC → Prisma schema: reads · Activity feeds are sourced from persisted activity records.
- Categories RPC → Prisma schema: reads · Category procedures read category data from storage.
- Accounting logic → Prisma schema: supports · Shared helpers and schemas sit alongside the persistence model.
- Accounting logic → Locale loading: localizes · Locale helpers feed UI and server-side messaging.
- Prisma schema → PostgreSQL: persists to · Prisma mediates access to the PostgreSQL database.
- Domain UI → UI primitives: composes · Domain-specific controls are built on shared primitives.
- Group pages → Domain UI: uses · Group views are assembled from reusable domain widgets.
- Domain UI → Locale loading: displays · UI labels and messages are locale-aware.
- Ops runtime → PostgreSQL: runs with · Local and containerized setups provision the database.
- Ops runtime → tRPC endpoint: deploys · Runtime tooling supports the application server and API.
- Ops runtime → S3 upload: supports · Deployment environment enables external storage integrations.
