# anacke8996/splitty architecture

> Architecture diagram of the GitHub repository anacke8996/splitty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anacke8996/splitty
- Repository: https://github.com/anacke8996/splitty

## Overview

##### Project type and purpose
- Splitty is a full-stack web application for splitting bills by scanning receipts and assigning items to users.
- The frontend is built with Next.js (React + TypeScript), serving both UI pages and API routes.
- There is no separate traditional backend folder; the project uses Next.js serverless functions (located under src/pages/api) to implement “backend” logic.
- It integrates with two external services: Mistral AI for OCR and ExchangeRate API for currency conversion.

##### File structure
Top-level:
- .gitignore, package.json, package-lock.json
- .venv (Python virtual env—likely unused or vestigial)
- README.md

splitty-frontend/ (Next.js app)
- .next/ (build output)
- public/ (static assets)
- src/
– pages/
- index.js (landing page)
- api/ (Next.js API routes)
– process-receipt.ts
– split-bill.ts
– test.ts
- _document.tsx, _app.tsx (Next.js wrappers)
– components/ (UI pieces: CurrencySelector, ReceiptProcessor)
– services/api.ts (HTTP helpers)
– config/api.ts (endpoint URLs)
– theme.ts, tailwind.config.js (styling)
- next.config.js, tsconfig.json

##### Key insights from README
- Describes features: image upload ➔ OCR ➔ currency detection/conversion ➔ assign items ➔ calculate splits
- Mentions Python/Flask backend and server.py, but file tree shows Next.js APIs instead
- Requires MISTRAL_API_KEY and EXCHANGE_API_KEY as env vars

##### Main system components
A. Client (Browser/Mobile via Web)
- Next.js UI (React pages + components)
- Tailwind CSS theme

B. API Layer (Next.js serverless functions)
- /api/process-receipt: accepts image, calls OCR service
- /api/split-bill: accepts item assignments, computes splits

C. External Services
- Mistral AI OCR API (image → text + line items)
- ExchangeRate API (currency code → USD rate)

D. (Optional) Data store or in-memory state
- No persistent DB—state lives in request/response; optional enhancement

##### Relationships and interactions
1. User uploads receipt from UI →
2. Browser performs POST to /api/process-receipt →
3. Next.js function forwards image to Mistral API →
4. Mistral returns parsed items + currencies →
5. Function calls ExchangeRate API (if needed) →
6. Normalized data sent back to UI →
7. User assigns items within React UI →
8. Browser POSTs assignments to /api/split-bill →
9. Serverless function computes per-person totals →
10. Results returned and rendered

##### Architectural patterns and principles
- Full-stack Next.js (UI + API co-located)
- Serverless backend functions (scalable, no server management)
- Single-page application routing with dynamic API endpoints
- Separation of concerns: UI components vs. service calls vs. config vs. styling

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        Pages["Next.js Frontend\nsrc/pages"]:::client
        Landing["Landing Page\nindex.js"]:::client
        AppWrapper["Custom App\n_app.tsx"]:::client
        DocWrapper["Custom Document\n_document.tsx"]:::client
        Components["UI Components\nsrc/components"]:::client
        ServiceCalls["HTTP Helpers\nsrc/services/api.ts"]:::client
        Config["External Config\nsrc/config/api.ts"]:::client
        ThemeTS["Theme Config\nsrc/theme.ts"]:::client
        TailwindCfg["Tailwind Config\ntailwind.config.js"]:::client
        VENV["Python Vestigial\n.venv"]:::client
        NextOut["Build Output\n.next"]:::client
    end

    %% API Layer
    subgraph "Next.js API Layer (Serverless)" 
        direction TB
        Proc["/api/process-receipt"]:::api
        SplitF["/api/split-bill"]:::api
        TestEP["/api/test"]:::api
        EnvVars["Env Vars\nMISTRAL_API_KEY\nEXCHANGE_API_KEY"]:::api
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OCR["Mistral AI OCR"]:::external
        Rate["ExchangeRate API"]:::external
    end

    %% Data Flows
    Landing -->|uploads image| Proc
    ServiceCalls -->|HTTP POST| Proc
    Proc -->|calls OCR| OCR
    OCR -->|parsed items| Proc
    Proc -->|calls Rate| Rate
    Rate -->|exchange rate| Proc
    Proc -->|returns data| Landing

    Landing -->|assign items| SplitF
    SplitF -->|split results| Landing

    %% Click Events
    click Pages "https://github.com/anacke8996/splitty/tree/main/splitty-frontend/src/pages"
    click Landing "https://github.com/anacke8996/splitty/blob/main/splitty-frontend/src/pages/index.js"
    click AppWrapper "https://github.com/anacke8996/splitty/blob/main/splitty-frontend/src/pages/_app.tsx"
    click DocWrapper "https://github.com/anacke8996/splitty/blob/main/splitty-frontend/src/pages/_document.tsx"
    click Components "https://github.com/anacke8996/splitty/tree/main/splitty-frontend/src/components"
    click ServiceCalls "https://github.com/anacke8996/splitty/blob/main/splitty-frontend/src/services/api.ts"
    click Config "https://github.com/anacke8996/splitty/blob/main/splitty-frontend/src/config/api.ts"
    click ThemeTS "https://github.com/anacke8996/splitty/blob/main/splitty-frontend/src/theme.ts"
    click TailwindCfg "https://github.com/anacke8996/splitty/blob/main/splitty-frontend/tailwind.config.js"
    click VENV "https://github.com/anacke8996/splitty/blob/main/.venv"
    click NextOut "https://github.com/anacke8996/splitty/blob/main/splitty-frontend/.next"
    click Proc "https://github.com/anacke8996/splitty/blob/main/splitty-frontend/src/pages/api/process-receipt.ts"
    click SplitF "https://github.com/anacke8996/splitty/blob/main/splitty-frontend/src/pages/api/split-bill.ts"
    click TestEP "https://github.com/anacke8996/splitty/blob/main/splitty-frontend/src/pages/api/test.ts"

    %% Styles
    classDef client fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef api fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef external fill:#fff3cd,stroke:#333,stroke-width:1px;
```
