How spliit-app/spliit works
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: schema.prisma Prisma schema · _app.ts App router · lib Accounting logic · compose.yaml Ops runtime
Components 20
Next.js app
App Router pages, layouts, and route handlers for the user-facing product.
- Home · Landing and top-level navigation entry point.
src/app/page.tsx - Groups area · Primary group-scoped UI shell and pages.
src/app/groups/[groupId] - Group pages · Expenses, balances, activity, info, stats, and edit views assembled from server and client components.
src/app/groups/[groupId] - Exports · 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 · HTTP bridge exposing the typed RPC API.
src/app/api/trpc/[trpc]/route.ts - App router · Composes feature routers into the application RPC surface.
src/trpc/routers/_app.ts - Groups RPC · Group create, get, update, list, details, and stats procedures.
src/trpc/routers/groups - Expenses RPC · Expense CRUD and listing procedures.
src/trpc/routers/groups/expenses - Balances RPC · Balance and reimbursement calculations.
src/trpc/routers/groups/balances - Activity RPC · Activity listing procedures.
src/trpc/routers/groups/activities - Categories RPC · Category listing procedures.
src/trpc/routers/categories
Persistence
Prisma schema, migrations, and PostgreSQL-backed data model.
- Prisma schema · Domain schema and migrations for groups, expenses, shares, categories, documents, activity, recurrence, and currency.
prisma/schema.prisma - PostgreSQL · Primary relational datastore.
Shared libs
Cross-cutting business logic, validation, locale, and infrastructure helpers.
- Accounting logic · Balances, totals, currency, validation, and health helpers.
src/lib - Locale loading · Locale resolution and message loading for the UI.
src/i18n/request.ts
UI system
Reusable domain components and base design-system primitives.
- UI primitives · Reusable shadcn-style components built on Tailwind.
src/components/ui - Domain UI · Group forms, expense forms, selectors, lists, and widgets.
src/components
Runtime & integrations
External services and deployment/runtime entry points.
- Health API · Readiness and liveness probes for deployment monitoring.
src/app/api/health - S3 upload · Upload endpoint for receipt and document storage.
src/app/api/s3-upload/route.ts - Ops runtime · Docker, devcontainer, scripts, and environment setup for local and containerized runs.
compose.yaml
Connections 26
- 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.