# sinennn/gigjar architecture

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

- Interactive diagram: https://gitdiagram.com/sinennn/gigjar
- Repository: https://github.com/sinennn/gigjar

## Overview

GigJar lets students create USDT payment links for gigs; clients pay into a per-student jar, and a watcher observes TRON transfers so payments can be attributed and confirmed. The API also supports account sessions, jar and payment-link management, and incoming-transfer views; the web screens are scaffolded around those capabilities. The README describes threshold-based sweeps to Cleva as the intended result, but says the sweeper is a future phase. Some internal calls and storage wiring are not visible in the excerpts, so uncertain links are omitted or dashed.

Main entry points: [`services/api/main.go`](https://github.com/sinennn/gigjar/blob/main/services/api/main.go) (API service), [`apps/web/src/lib/api/client.ts`](https://github.com/sinennn/gigjar/blob/main/apps/web/src/lib/api/client.ts) (API client), [`internal/httpapi/router.go`](https://github.com/sinennn/gigjar/blob/main/internal/httpapi/router.go) (HTTP router), [`internal/httpapi/paylink_handlers.go`](https://github.com/sinennn/gigjar/blob/main/internal/httpapi/paylink_handlers.go) (Payment-link handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_links["Link screens<br/>[page.tsx]"]
  node_web_public["Public pay page<br/>[page.tsx]"]
  node_web_overview["Jar overview<br/>[page.tsx]"]
  node_web_activity["Activity screens<br/>[page.tsx]"]
  node_web_settlements["Settlement screen<br/>[page.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and identity"]
  node_api_service["API service<br/>[main.go]"]
  node_router["HTTP router<br/>[router.go]"]
  node_auth_handlers["Auth handlers<br/>[auth_handlers.go]"]
  node_identity["Identity service<br/>[identity.go]"]
  node_sessions["Session handling<br/>[sessions.go]"]
  node_jar_handlers["Jar handlers<br/>[jar_handlers.go]"]
  node_link_handlers["Payment-link handlers"]
  node_transfer_handlers["Transfer handlers"]
end

subgraph group_payments["Payment domain"]
  node_paylinks["Payment links<br/>[paylinks.go]"]
  node_jars["Student jars<br/>[jars.go]"]
  node_transfers["Incoming transfers<br/>[transfers.go]"]
  node_ledger["Double-entry ledger<br/>[ledger.go]"]
end

subgraph group_watcher["Chain observation"]
  node_watcher_service["Watcher service<br/>[watcher.go]"]
  node_reconcile["Reconciliation<br/>[reconcile.go]"]
  node_chain_provider["Chain provider<br/>[chain.go]"]
  node_simulated_chain["Simulated chain<br/>[simulated.go]"]
  node_trongrid["TronGrid provider<br/>[trongrid.go]"]
end

subgraph group_platform["Persistence and configuration"]
  node_database[("Postgres access<br/>[database.go]")]
  node_config["Runtime config<br/>[config.go]"]
end

node_student(("Student"))
node_client(("Gig client"))

node_student -->|"creates links"| node_web_links
node_client -->|"opens link"| node_web_public
node_web_links -.->|"requests API"| node_api_client
node_web_public -.->|"requests API"| node_api_client
node_api_client -->|"fetches /api"| node_api_service
node_student -->|"uses account"| node_api_service
node_api_service -->|"connects"| node_database
node_api_service -->|"constructs"| node_identity
node_api_service -->|"constructs"| node_router
node_router -.->|"routes requests"| node_auth_handlers
node_router -.->|"routes requests"| node_jar_handlers
node_router -.->|"routes requests"| node_link_handlers
node_router -.->|"routes requests"| node_transfer_handlers
node_auth_handlers -->|"calls identity"| node_identity
node_identity -.->|"manages sessions"| node_sessions
node_api_service -->|"constructs service"| node_jars
node_api_service -->|"constructs service"| node_paylinks
node_link_handlers -->|"creates and reads"| node_paylinks
node_link_handlers -->|"loads link transfers"| node_transfers
node_link_handlers -->|"wakes watcher"| node_jars
node_transfer_handlers -->|"lists transfers"| node_transfers
node_transfer_handlers -->|"resolves reference"| node_paylinks
node_transfer_handlers -->|"sends simulated payment"| node_simulated_chain
node_watcher_service -.->|"observes chain"| node_chain_provider
node_watcher_service -.->|"records observations"| node_transfers
node_watcher_service -.->|"posts confirmations"| node_ledger
node_reconcile -.->|"checks balances"| node_ledger
node_simulated_chain -->|"implements"| node_chain_provider
node_trongrid -->|"implements"| node_chain_provider
node_web_overview -->|"uses endpoints"| node_api_client
node_web_activity -.->|"uses endpoints"| node_api_client
node_web_settlements -.->|"uses endpoints"| node_api_client
node_student -->|"reviews jar"| node_web_overview
node_config -->|"configures startup"| node_api_service
node_config -->|"configures watcher"| node_watcher_service

click node_web_links "https://github.com/sinennn/gigjar/blob/main/apps/web/src/app/(app)/links/page.tsx"
click node_web_public "https://github.com/sinennn/gigjar/blob/main/apps/web/src/app/pay/%5Breference%5D/page.tsx"
click node_web_overview "https://github.com/sinennn/gigjar/blob/main/apps/web/src/app/(app)/dashboard/page.tsx"
click node_web_activity "https://github.com/sinennn/gigjar/blob/main/apps/web/src/app/(app)/transactions/page.tsx"
click node_web_settlements "https://github.com/sinennn/gigjar/blob/main/apps/web/src/app/(app)/settlements/page.tsx"
click node_api_client "https://github.com/sinennn/gigjar/blob/main/apps/web/src/lib/api/client.ts"
click node_api_service "https://github.com/sinennn/gigjar/blob/main/services/api/main.go"
click node_router "https://github.com/sinennn/gigjar/blob/main/internal/httpapi/router.go"
click node_auth_handlers "https://github.com/sinennn/gigjar/blob/main/internal/httpapi/auth_handlers.go"
click node_identity "https://github.com/sinennn/gigjar/blob/main/internal/identity/identity.go"
click node_sessions "https://github.com/sinennn/gigjar/blob/main/internal/identity/sessions.go"
click node_jar_handlers "https://github.com/sinennn/gigjar/blob/main/internal/httpapi/jar_handlers.go"
click node_link_handlers "https://github.com/sinennn/gigjar/blob/main/internal/httpapi/paylink_handlers.go"
click node_transfer_handlers "https://github.com/sinennn/gigjar/blob/main/internal/httpapi/transfer_handlers.go"
click node_paylinks "https://github.com/sinennn/gigjar/blob/main/internal/paylinks/paylinks.go"
click node_jars "https://github.com/sinennn/gigjar/blob/main/internal/jars/jars.go"
click node_transfers "https://github.com/sinennn/gigjar/blob/main/internal/transfers/transfers.go"
click node_ledger "https://github.com/sinennn/gigjar/blob/main/internal/ledger/ledger.go"
click node_watcher_service "https://github.com/sinennn/gigjar/blob/main/internal/watcher/watcher.go"
click node_reconcile "https://github.com/sinennn/gigjar/blob/main/internal/watcher/reconcile.go"
click node_chain_provider "https://github.com/sinennn/gigjar/blob/main/internal/chain/chain.go"
click node_simulated_chain "https://github.com/sinennn/gigjar/blob/main/internal/chain/simulated/simulated.go"
click node_trongrid "https://github.com/sinennn/gigjar/blob/main/internal/chain/trongrid/trongrid.go"
click node_database "https://github.com/sinennn/gigjar/blob/main/internal/database/database.go"
click node_config "https://github.com/sinennn/gigjar/blob/main/internal/config/config.go"

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_web_links,node_web_public,node_web_overview,node_web_activity,node_web_settlements,node_api_client,node_client toneBlue
class node_api_service,node_router,node_auth_handlers,node_identity,node_sessions,node_jar_handlers,node_link_handlers,node_transfer_handlers toneAmber
class node_paylinks,node_jars,node_transfers,node_ledger toneMint
class node_watcher_service,node_reconcile,node_chain_provider,node_simulated_chain,node_trongrid toneRose
class node_database,node_config,node_student toneIndigo
```

## Components

### Web experience

- [Link screens](https://github.com/sinennn/gigjar/blob/main/apps/web/src/app/(app)/links/page.tsx): `apps/web/src/app/(app)/links/page.tsx`
- [Public pay page](https://github.com/sinennn/gigjar/blob/main/apps/web/src/app/pay/%5Breference%5D/page.tsx): `apps/web/src/app/pay/[reference]/page.tsx`
- [Jar overview](https://github.com/sinennn/gigjar/blob/main/apps/web/src/app/(app)/dashboard/page.tsx): `apps/web/src/app/(app)/dashboard/page.tsx`
- [Activity screens](https://github.com/sinennn/gigjar/blob/main/apps/web/src/app/(app)/transactions/page.tsx): `apps/web/src/app/(app)/transactions/page.tsx`
- [Settlement screen](https://github.com/sinennn/gigjar/blob/main/apps/web/src/app/(app)/settlements/page.tsx): `apps/web/src/app/(app)/settlements/page.tsx`
- [API client](https://github.com/sinennn/gigjar/blob/main/apps/web/src/lib/api/client.ts): `apps/web/src/lib/api/client.ts`

### API and identity

- [API service](https://github.com/sinennn/gigjar/blob/main/services/api/main.go): `services/api/main.go`
- [HTTP router](https://github.com/sinennn/gigjar/blob/main/internal/httpapi/router.go): `internal/httpapi/router.go`
- [Auth handlers](https://github.com/sinennn/gigjar/blob/main/internal/httpapi/auth_handlers.go): `internal/httpapi/auth_handlers.go`
- [Identity service](https://github.com/sinennn/gigjar/blob/main/internal/identity/identity.go): `internal/identity/identity.go`
- [Session handling](https://github.com/sinennn/gigjar/blob/main/internal/identity/sessions.go): `internal/identity/sessions.go`
- [Jar handlers](https://github.com/sinennn/gigjar/blob/main/internal/httpapi/jar_handlers.go): `internal/httpapi/jar_handlers.go`
- [Payment-link handlers](https://github.com/sinennn/gigjar/blob/main/internal/httpapi/paylink_handlers.go): `internal/httpapi/paylink_handlers.go`
- [Transfer handlers](https://github.com/sinennn/gigjar/blob/main/internal/httpapi/transfer_handlers.go): `internal/httpapi/transfer_handlers.go`

### Payment domain

- [Payment links](https://github.com/sinennn/gigjar/blob/main/internal/paylinks/paylinks.go): `internal/paylinks/paylinks.go`
- [Student jars](https://github.com/sinennn/gigjar/blob/main/internal/jars/jars.go): `internal/jars/jars.go`
- [Incoming transfers](https://github.com/sinennn/gigjar/blob/main/internal/transfers/transfers.go): `internal/transfers/transfers.go`
- [Double-entry ledger](https://github.com/sinennn/gigjar/blob/main/internal/ledger/ledger.go): `internal/ledger/ledger.go`

### Chain observation

- [Watcher service](https://github.com/sinennn/gigjar/blob/main/internal/watcher/watcher.go): `internal/watcher/watcher.go`
- [Reconciliation](https://github.com/sinennn/gigjar/blob/main/internal/watcher/reconcile.go): `internal/watcher/reconcile.go`
- [Chain provider](https://github.com/sinennn/gigjar/blob/main/internal/chain/chain.go): `internal/chain/chain.go`
- [Simulated chain](https://github.com/sinennn/gigjar/blob/main/internal/chain/simulated/simulated.go): `internal/chain/simulated/simulated.go`
- [TronGrid provider](https://github.com/sinennn/gigjar/blob/main/internal/chain/trongrid/trongrid.go): `internal/chain/trongrid/trongrid.go`

### Persistence and configuration

- [Postgres access](https://github.com/sinennn/gigjar/blob/main/internal/database/database.go): `internal/database/database.go`
- [Runtime config](https://github.com/sinennn/gigjar/blob/main/internal/config/config.go): `internal/config/config.go`

### Other components

- **Student**
- **Gig client**

## Connections

- Student → Link screens: creates links (evidence: `README.md`)
- Gig client → Public pay page: opens link (evidence: `apps/web/src/app/pay/[reference]/page.tsx`)
- Link screens → API client: requests API
- Public pay page → API client: requests API
- API client → API service: fetches /api (evidence: `README.md`)
- Student → API service: uses account (evidence: `README.md`)
- API service → Postgres access: connects (evidence: `services/api/main.go`)
- API service → Identity service: constructs (evidence: `services/api/main.go`)
- API service → HTTP router: constructs (evidence: `services/api/main.go`)
- HTTP router → Auth handlers: routes requests
- HTTP router → Jar handlers: routes requests
- HTTP router → Payment-link handlers: routes requests
- HTTP router → Transfer handlers: routes requests
- Auth handlers → Identity service: calls identity (evidence: `internal/httpapi/auth_handlers.go`)
- Identity service → Session handling: manages sessions
- API service → Student jars: constructs service (evidence: `services/api/main.go`)
- API service → Payment links: constructs service (evidence: `services/api/main.go`)
- Payment-link handlers → Payment links: creates and reads (evidence: `internal/httpapi/paylink_handlers.go`)
- Payment-link handlers → Incoming transfers: loads link transfers (evidence: `internal/httpapi/paylink_handlers.go`)
- Payment-link handlers → Student jars: wakes watcher (evidence: `internal/httpapi/paylink_handlers.go`)
- Transfer handlers → Incoming transfers: lists transfers (evidence: `internal/httpapi/transfer_handlers.go`)
- Transfer handlers → Payment links: resolves reference (evidence: `internal/httpapi/transfer_handlers.go`)
- Transfer handlers → Simulated chain: sends simulated payment (evidence: `internal/httpapi/transfer_handlers.go`)
- Watcher service → Chain provider: observes chain
- Watcher service → Incoming transfers: records observations
- Watcher service → Double-entry ledger: posts confirmations
- Reconciliation → Double-entry ledger: checks balances
- Simulated chain → Chain provider: implements (evidence: `internal/chain/simulated/simulated.go`)
- TronGrid provider → Chain provider: implements (evidence: `internal/chain/trongrid/trongrid.go`)
- Jar overview → API client: uses endpoints (evidence: `apps/web/src/app/(app)/dashboard/page.tsx`)
- Activity screens → API client: uses endpoints
- Settlement screen → API client: uses endpoints
- Student → Jar overview: reviews jar (evidence: `apps/web/src/app/(app)/dashboard/page.tsx`)
- Runtime config → API service: configures startup (evidence: `services/api/main.go`)
- Runtime config → Watcher service: configures watcher