# dynonguyen/ezbill architecture

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

- Interactive diagram: https://gitdiagram.com/dynonguyen/ezbill
- Repository: https://github.com/dynonguyen/ezbill

## Overview

##### Project Type and Purpose
- This is a full-stack, single-page web application (SPA) called “Ezbill” for splitting bills among group members.
- The front end is built with Vue 3 + Vite, and the back end is provided entirely by Supabase (Postgres, Auth, Realtime, REST API, storage), orchestrated locally via Docker for development.

##### High-Level Architecture Overview
- Users interact through their web browser (Chrome, Safari, etc.).
- Static assets (HTML/CSS/JS) are hosted on Vercel’s CDN and fetched by the browser.
- The Vue app (components, features, router, state, supabase.ts client) communicates with Supabase endpoints.
- Supabase services include Auth, PostgREST (auto-generated REST API), Realtime (WebSockets), Postgres DB, connection pooler, vector for logs, and optional storage.

##### Main Components and Relationships
a. Frontend (Client Side)
- Browser (User agent)
- CDN / Vercel (Static asset hosting)
- Vue 3 SPA (src/main.ts, App.vue, pages, components, stores, routes, supabase.ts)
b. Backend-as-a-Service (Supabase)
- Kong API Gateway (routes incoming HTTP to Supabase components)
- PostgREST (translates HTTP requests to SQL queries)
- Realtime Server (pushes DB events via WebSockets)
- Auth Server (sign-up, sign-in flows)
- Postgres DB (schema defined via SQL in docker/volumes/db/init/*.sql)
- Pooler (pgBouncer)
- Vector (aggregates logs)
- Storage & Functions (if used)
c. Local Development Environment
- Docker Compose (docker/dev/docker-compose.dev.yml orchestrates Kong, Postgres, PostgREST, Realtime, pooler, vector)
- Seed scripts (docker/dev/data.sql, docker/volumes/db/init/*.sql)

##### Data-Flow and Interaction
- Browser loads index.html → downloads JS bundles from Vercel.
- Vue app initializes Supabase client (supabase.ts) using environment variables.
- On user actions (create/join group, add bill, fetch lists), Vue calls supabase.from(…) → HTTP(s) to Kong → forwarded to PostgREST or Auth.
- For real-time updates (new bills, member changes), Vue subscribes to channels via Supabase Realtime → WebSocket connection.
- Supabase writes to Postgres → pooler ensures efficient DB connections → Realtime pushes change events → front end updates UI.
- Vector collects logs from all services into a unified store (for debugging).

##### Architectural Patterns and Principles
- SPA / Client-Server separation
- BaaS (Backend-as-a-Service): no custom server code → leverage Supabase microservices
- Event-driven updates via WebSockets (Realtime)
- Clear separation between UI components (views, form controls, dialogs) and data access layer (supabase.ts, stores, hooks)
- Dockerized development environment for reproducible local Supabase stack

##### Final Checklist
- All components clearly labeled.
- Docker boundary for local dev.
- Annotations referencing key files or modules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    Browser["Browser (Chrome, Safari)"]:::user
    CDN["CDN / Vercel"]:::infra

    subgraph "Frontend"
        direction TB
        Vue["Vue SPA"]:::frontend

        subgraph "App Structure"
            direction TB
            Entry["src/main.ts"]:::file
            AppComp["src/App.vue"]:::file
            Pages["src/pages"]:::file
            Router["src/routes/router.ts"]:::file
            Stores["src/stores"]:::file
            SupabaseClient["src/apis/supabase.ts"]:::file
            Components["src/components"]:::file
            Features["src/features"]:::file
            Hook["src/features/group-detail/hooks/useRealtimeChannel.ts"]:::file
        end
    end

    click Entry "https://github.com/dynonguyen/ezbill/blob/main/src/main.ts"
    click AppComp "https://github.com/dynonguyen/ezbill/blob/main/src/App.vue"
    click Pages "https://github.com/dynonguyen/ezbill/tree/main/src/pages"
    click Router "https://github.com/dynonguyen/ezbill/blob/main/src/routes/router.ts"
    click Stores "https://github.com/dynonguyen/ezbill/tree/main/src/stores"
    click SupabaseClient "https://github.com/dynonguyen/ezbill/blob/main/src/apis/supabase.ts"
    click Components "https://github.com/dynonguyen/ezbill/tree/main/src/components"
    click Features "https://github.com/dynonguyen/ezbill/tree/main/src/features"
    click Hook "https://github.com/dynonguyen/ezbill/blob/main/src/features/group-detail/hooks/useRealtimeChannel.ts"

    Browser -->|Fetch assets| CDN
    CDN -->|Serves JS/CSS/HTML| Vue

    subgraph "Supabase Cluster"
        direction TB
        Kong["Kong API Gateway"]:::backend
        PostgREST["PostgREST"]:::backend
        Auth["Auth Server"]:::backend
        Realtime["Realtime Server"]:::backend
        Postgres["Postgres DB"]:::db
        Pooler["pgBouncer"]:::infra
        Vector["Vector Logs"]:::log
        Storage["Storage & Functions"]:::backend
    end

    subgraph "Local Docker Dev" style dashed
        direction TB
        Compose["docker-compose.dev.yml"]:::file
        Kong
        PostgREST
        Auth
        Realtime
        Postgres
        Pooler
        Vector
    end

    click Compose "https://github.com/dynonguyen/ezbill/blob/main/docker/dev/docker-compose.dev.yml"
    click Kong "https://github.com/dynonguyen/ezbill/blob/main/docker/volumes/api/kong.yml"
    click Postgres "https://github.com/dynonguyen/ezbill/blob/main/docker/volumes/db/init/*.sql"
    click Pooler "https://github.com/dynonguyen/ezbill/blob/main/docker/volumes/pooler/pooler.exs"
    click Vector "https://github.com/dynonguyen/ezbill/blob/main/docker/volumes/logs/vector.yml"
    click Scripts "https://github.com/dynonguyen/ezbill/blob/main/scripts/migration.sql"

    Vue -->|HTTPS Requests| Kong
    Kong -->|Forward REST| PostgREST
    Kong -->|Forward Auth| Auth
    Vue -->|WSS Connect| Realtime
    PostgREST -->|SQL Queries| Postgres
    Auth -->|SQL Queries| Postgres
    Postgres -->|DB Pool| Pooler
    Pooler -->|Serve Connections| PostgREST
    Postgres -->|Emit Events| Realtime

    PostgREST -->|Logs| Vector
    Auth -->|Logs| Vector
    Realtime -->|Logs| Vector
    Vue -->|Client Logs| Vector
    CDN -->|Logs| Vector

    classDef user fill:#FFD79F,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef frontend fill:#A3D5FF,stroke:#333,stroke-width:1px
    classDef backend fill:#FFB2B2,stroke:#333,stroke-width:1px
    classDef db fill:#FFE599,stroke:#333,stroke-width:1px
    classDef log fill:#C4FCEF,stroke:#333,stroke-width:1px
    classDef file fill:#FFFFFF,stroke:#000,stroke-dasharray:2 2

    subgraph Legend
        direction TB
        U["User-facing Components"]:::user
        F["Frontend Components"]:::frontend
        B["Backend Services"]:::backend
        D["Database"]:::db
        I["Infrastructure"]:::infra
        L["Logging"]:::log
        FI["Config/Files"]:::file
    end
```
