# bnjmzzn/seedbank architecture

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

- Interactive diagram: https://gitdiagram.com/bnjmzzn/seedbank
- Repository: https://github.com/bnjmzzn/seedbank

## Overview

1. **What this repository is**
   Seedbank is a Next.js + TypeScript full-stack app built around a single game economy: users log in, earn or spend “seeds,” play minigames, transfer seeds, steal from others, and climb a balance-based leaderboard. The app is deployed on Vercel and persists data in Supabase PostgreSQL.

2. **Top-level application shape**
   The codebase is split into two main route groups: `src/app/(site)` for the user-facing UI and `src/app/(api)` for HTTP endpoints. That separation is the core architectural boundary: React pages/components handle presentation, while the API routes own all state-changing business logic.

3. **Frontend shell and navigation**
   The site uses a shared app layout plus reusable UI primitives from `src/components/ui` and shared elements like `Navbar` and `Logo`. The main authenticated experience is centered on `/dashboard`, which acts as a hub linking to games, transfer, leaderboard, and profile views. There is also a `/login` entry point with onboarding content.

4. **Game subsystem**
   Each minigame has its own route and component set under `src/app/(site)/games/*`:
   - coinflip
   - dice
   - color
   - bomb
   - race  
   The frontend primarily renders forms, pickers, and result states. The actual outcome generation and balance changes are not computed in the browser; they are delegated to the server through the shared play API.

5. **API surface**
   The backend is organized into feature-specific route handlers under `src/app/(api)/api/*`:
   - auth: login/register
   - daily: daily reward claim
   - play: game resolution
   - steal: stealing seeds
   - transfer: sending seeds to another user
   - leaderboard: rank retrieval
   - users: profile and history lookups  
   These routes form the external contract for the app and are the main integration points for the frontend.

6. **Server architecture layers**
   The server code is intentionally layered:
   - `src/lib/server/api` for response shaping
   - `src/lib/server/services` for business rules
   - `src/lib/server/db` for database queries  
   The README’s architecture matches the code: API routes validate and normalize input, services implement domain logic, and db modules perform direct persistence. This keeps game rules, transfer logic, and history logging out of route handlers.

7. **Domain model and data persistence**
   The database is centered on two tables in `database/schema.sql`:
   - `users`: identity, username, password hash, balance, created time
   - `history`: per-user ledger of balance changes with reason and optional JSON metadata  
   A key invariant is that balance mutations also write a history record in the same service call. That makes history the audit trail for daily rewards, games, steals, and transfers.

8. **Authentication and request protection**
   Auth uses password hashing plus JWTs via `jose`. Client-side auth helpers live in `src/lib/client/auth.ts`, while server-side auth/config helpers live under `src/lib/server`. The app includes a `src/proxy.ts`, which likely enforces route guarding or token checks before requests reach protected pages. The user experience is designed so unauthenticated traffic is redirected to `/login`.

9. **Validation and client/server contract**
   Form validation is shared and explicit: the frontend validates inputs with Zod and React Hook Form, but the server still performs its own final validation on receipt. That dual validation boundary is important because the API is the final authority for wager amounts, recipient usernames, and other sensitive actions.

10. **Profiles, history, and leaderboard reads**
   Read-only views are split by concern:
   - leaderboard ranks users by balance
   - profile pages show a user summary and activity history
   - transfer and steal pages surface past interactions  
   These views all consume API data rather than reading the database directly, so the frontend stays decoupled from storage structure.

11. **API documentation and external contract**
   The repository includes `src/openapi.ts` and a `/api/docs` route, indicating that the API is documented as a formal contract. This matters architecturally because the backend is not just page-driven; it exposes a stable REST surface intended for inspection and integration.

12. **Testing and quality boundaries**
   API behavior is covered by Vitest tests in `src/tests/api`, with focused coverage for auth, daily claims, leaderboard, play, steal, transfer, and users endpoints. That test layout mirrors the service boundaries, so the tests help validate the separation between routing, business logic, and persistence.

13. **Infrastructure and runtime**
   The stack is Next.js on Vercel with Tailwind/shadcn for UI and Supabase PostgreSQL for storage. Environment variables provide the Supabase connection, JWT secret, and password hashing cost. Vercel’s hosting also serves as the app’s rate-limiting layer per the README.

14. **Main data flow to capture in a diagram**
   The most important flow is: user action in a React page → validated request to a Next.js API route → service layer applies game/auth/transfer rules → db layer updates `users` and appends `history` → response returns to the UI. Most features in the repo are variations of that same flow with different business rules and read models.

Main entry points: [`src/lib/server/services`](https://github.com/bnjmzzn/seedbank/tree/main/src/lib/server/services) (Services), [`src/app/login/page.tsx`](https://github.com/bnjmzzn/seedbank/blob/main/src/app/login/page.tsx) (Login), [`src/app/(site)/transfer/page.tsx`](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/transfer/page.tsx) (Transfer), [`src/app/(site)/games/steal/page.tsx`](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/games/steal/page.tsx) (Steal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Site UI"]
  node_layout["App shell<br/>site layout<br/>[layout.tsx]"]
  node_site_layout["Site layout<br/>route layout<br/>[layout.tsx]"]
  node_login["Login<br/>entry page<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>hub page<br/>[page.tsx]"]
  node_games["Games<br/>minigame suite"]
  node_leaderboard["Leaderboard<br/>read page<br/>[page.tsx]"]
  node_profile["Profile<br/>read page<br/>[page.tsx]"]
  node_transfer_page["Transfer<br/>action page<br/>[page.tsx]"]
  node_steal_page["Steal<br/>action page<br/>[page.tsx]"]
end

subgraph group_api["API Routes"]
  node_auth_api["Auth API<br/>route handlers"]
  node_daily_api["Daily API<br/>route handler<br/>[route.ts]"]
  node_play_api["Play API<br/>route handler<br/>[route.ts]"]
  node_steal_api["Steal API<br/>route handler<br/>[route.ts]"]
  node_transfer_api["Transfer API<br/>route handler<br/>[route.ts]"]
  node_leaderboard_api["Leaderboard API<br/>route handler<br/>[route.ts]"]
  node_users_api["Users API<br/>route handlers"]
  node_docs_api["Docs API<br/>docs route<br/>[route.ts]"]
end

subgraph group_server["Server Core"]
  node_response["API response<br/>server helper<br/>[response.ts]"]
  node_services["Services<br/>domain logic"]
  node_db["DB layer<br/>persistence"]
  node_config["Server config<br/>runtime config<br/>[config.ts]"]
end

subgraph group_data["Data Model"]
  node_schema[("Schema<br/>[schema.sql]")]
  node_users_table["Users table<br/>entity<br/>[schema.sql]"]
  node_history_table["History table<br/>ledger<br/>[schema.sql]"]
end

subgraph group_shared["Shared UI"]
  node_shared_ui["UI primitives<br/>component library"]
  node_shared_nav["Navbar<br/>shared component<br/>[Navbar.tsx]"]
  node_client_auth["Client auth<br/>client helper<br/>[auth.ts]"]
  node_validators["Validators<br/>form schema<br/>[validators.ts]"]
end

node_root["Seedbank<br/>Next.js app"]

node_root -->|"uses"| node_layout
node_root -->|"contains"| node_site_layout
node_root -->|"entry"| node_login
node_root -->|"routes to"| node_dashboard
node_root -->|"contains"| node_games
node_root -->|"exposes"| node_leaderboard
node_root -->|"exposes"| node_profile
node_root -->|"exposes"| node_transfer_page
node_root -->|"exposes"| node_steal_page
node_site_layout -->|"uses"| node_shared_nav
node_site_layout -->|"renders with"| node_shared_ui
node_login -->|"calls"| node_auth_api
node_dashboard -->|"calls"| node_daily_api
node_games -->|"calls"| node_play_api
node_steal_page -->|"calls"| node_steal_api
node_transfer_page -->|"calls"| node_transfer_api
node_leaderboard -->|"reads"| node_leaderboard_api
node_profile -->|"reads"| node_users_api
node_steal_page -->|"reads"| node_users_api
node_transfer_page -->|"reads"| node_users_api
node_auth_api -->|"uses"| node_response
node_daily_api -->|"delegates"| node_services
node_play_api -->|"delegates"| node_services
node_steal_api -->|"delegates"| node_services
node_transfer_api -->|"delegates"| node_services
node_leaderboard_api -->|"delegates"| node_services
node_users_api -->|"delegates"| node_services
node_services -->|"queries"| node_db
node_db -->|"persists to"| node_schema
node_schema -->|"contains"| node_users_table
node_schema -->|"contains"| node_history_table
node_services -->|"appends"| node_history_table
node_services -->|"uses"| node_config
node_login -->|"uses"| node_client_auth
node_login -->|"uses"| node_validators
node_games -->|"uses"| node_validators
node_transfer_page -->|"uses"| node_validators
node_steal_page -->|"uses"| node_validators
node_docs_api -->|"uses"| node_response

click node_layout "https://github.com/bnjmzzn/seedbank/blob/main/src/app/layout.tsx"
click node_site_layout "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/layout.tsx"
click node_login "https://github.com/bnjmzzn/seedbank/blob/main/src/app/login/page.tsx"
click node_dashboard "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/dashboard/page.tsx"
click node_games "https://github.com/bnjmzzn/seedbank/tree/main/src/app/(site)/games"
click node_leaderboard "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/leaderboard/page.tsx"
click node_profile "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/profile/[username]/page.tsx"
click node_transfer_page "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/transfer/page.tsx"
click node_steal_page "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/games/steal/page.tsx"
click node_auth_api "https://github.com/bnjmzzn/seedbank/tree/main/src/app/(api)/api/auth"
click node_daily_api "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/daily/route.ts"
click node_play_api "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/play/route.ts"
click node_steal_api "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/steal/route.ts"
click node_transfer_api "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/transfer/route.ts"
click node_leaderboard_api "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/leaderboard/route.ts"
click node_users_api "https://github.com/bnjmzzn/seedbank/tree/main/src/app/(api)/api/users"
click node_docs_api "https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/docs/route.ts"
click node_response "https://github.com/bnjmzzn/seedbank/blob/main/src/lib/server/api/response.ts"
click node_services "https://github.com/bnjmzzn/seedbank/tree/main/src/lib/server/services"
click node_db "https://github.com/bnjmzzn/seedbank/tree/main/src/lib/server/db"
click node_config "https://github.com/bnjmzzn/seedbank/blob/main/src/lib/server/config.ts"
click node_schema "https://github.com/bnjmzzn/seedbank/blob/main/database/schema.sql"
click node_users_table "https://github.com/bnjmzzn/seedbank/blob/main/database/schema.sql"
click node_history_table "https://github.com/bnjmzzn/seedbank/blob/main/database/schema.sql"
click node_shared_ui "https://github.com/bnjmzzn/seedbank/tree/main/src/components/ui"
click node_shared_nav "https://github.com/bnjmzzn/seedbank/blob/main/src/components/shared/Navbar.tsx"
click node_client_auth "https://github.com/bnjmzzn/seedbank/blob/main/src/lib/client/auth.ts"
click node_validators "https://github.com/bnjmzzn/seedbank/blob/main/src/lib/client/validators.ts"

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_layout,node_site_layout,node_login,node_dashboard,node_games,node_leaderboard,node_profile,node_transfer_page,node_steal_page toneBlue
class node_auth_api,node_daily_api,node_play_api,node_steal_api,node_transfer_api,node_leaderboard_api,node_users_api,node_docs_api toneAmber
class node_response,node_services,node_db,node_config toneMint
class node_schema,node_users_table,node_history_table toneRose
class node_shared_ui,node_shared_nav,node_client_auth,node_validators toneIndigo
class node_root toneNeutral
```

## Components

### Site UI

Authenticated pages and client-side game flows

- [App shell](https://github.com/bnjmzzn/seedbank/blob/main/src/app/layout.tsx): site layout · Global site layout and navigation shell · `src/app/layout.tsx`
- [Site layout](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/layout.tsx): route layout · Authenticated site wrapper for dashboard and feature pages · `src/app/(site)/layout.tsx`
- [Login](https://github.com/bnjmzzn/seedbank/blob/main/src/app/login/page.tsx): entry page · Authentication entry point with onboarding content · `src/app/login/page.tsx`
- [Dashboard](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/dashboard/page.tsx): hub page · Authenticated landing page linking to games and account actions · `src/app/(site)/dashboard/page.tsx`
- [Games](https://github.com/bnjmzzn/seedbank/tree/main/src/app/(site)/games): minigame suite · Browser-facing game pages for wager setup and result display · `src/app/(site)/games`
- [Leaderboard](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/leaderboard/page.tsx): read page · Rankings view based on user balances · `src/app/(site)/leaderboard/page.tsx`
- [Profile](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/profile/[username]/page.tsx): read page · User summary and activity history view · `src/app/(site)/profile/[username]/page.tsx`
- [Transfer](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/transfer/page.tsx): action page · Send seeds to another user and review transfer history · `src/app/(site)/transfer/page.tsx`
- [Steal](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(site)/games/steal/page.tsx): action page · Steal seeds from other users and review steal history · `src/app/(site)/games/steal/page.tsx`

### API Routes

Next.js route handlers for all state-changing and read operations

- [Auth API](https://github.com/bnjmzzn/seedbank/tree/main/src/app/(api)/api/auth): route handlers · Login and registration endpoints · `src/app/(api)/api/auth`
- [Daily API](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/daily/route.ts): route handler · Daily reward claim endpoint · `src/app/(api)/api/daily/route.ts`
- [Play API](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/play/route.ts): route handler · Resolves game outcomes and balance changes · `src/app/(api)/api/play/route.ts`
- [Steal API](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/steal/route.ts): route handler · Steal action endpoint · `src/app/(api)/api/steal/route.ts`
- [Transfer API](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/transfer/route.ts): route handler · Seed transfer endpoint · `src/app/(api)/api/transfer/route.ts`
- [Leaderboard API](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/leaderboard/route.ts): route handler · Rank retrieval endpoint · `src/app/(api)/api/leaderboard/route.ts`
- [Users API](https://github.com/bnjmzzn/seedbank/tree/main/src/app/(api)/api/users): route handlers · Profile and history lookup endpoints · `src/app/(api)/api/users`
- [Docs API](https://github.com/bnjmzzn/seedbank/blob/main/src/app/(api)/api/docs/route.ts): docs route · Published API documentation endpoint · `src/app/(api)/api/docs/route.ts`

### Server Core

Shared validation, response shaping, services, and database access

- [API response](https://github.com/bnjmzzn/seedbank/blob/main/src/lib/server/api/response.ts): server helper · Shared response shaping and normalization · `src/lib/server/api/response.ts`
- [Services](https://github.com/bnjmzzn/seedbank/tree/main/src/lib/server/services): domain logic · Business rules for auth-adjacent flows, games, transfers, leaderboard, and users · `src/lib/server/services`
- [DB layer](https://github.com/bnjmzzn/seedbank/tree/main/src/lib/server/db): persistence · Direct database queries and mutations · `src/lib/server/db`
- [Server config](https://github.com/bnjmzzn/seedbank/blob/main/src/lib/server/config.ts): runtime config · Server-side environment and auth configuration · `src/lib/server/config.ts`

### Data Model

Persistent schema and audit trail

- [Schema](https://github.com/bnjmzzn/seedbank/blob/main/database/schema.sql): postgres schema · users and history tables with balance ledger semantics · `database/schema.sql`
- [Users table](https://github.com/bnjmzzn/seedbank/blob/main/database/schema.sql): entity · Identity, credentials, balance, and timestamps · `database/schema.sql`
- [History table](https://github.com/bnjmzzn/seedbank/blob/main/database/schema.sql): ledger · Per-user balance change audit trail with reasons and metadata · `database/schema.sql`

### Shared UI

Reusable client-facing components and helpers

- [UI primitives](https://github.com/bnjmzzn/seedbank/tree/main/src/components/ui): component library · Reusable shared components used across pages · `src/components/ui`
- [Navbar](https://github.com/bnjmzzn/seedbank/blob/main/src/components/shared/Navbar.tsx): shared component · Top-level navigation for the app · `src/components/shared/Navbar.tsx`
- [Client auth](https://github.com/bnjmzzn/seedbank/blob/main/src/lib/client/auth.ts): client helper · Browser auth state and token helpers · `src/lib/client/auth.ts`
- [Validators](https://github.com/bnjmzzn/seedbank/blob/main/src/lib/client/validators.ts): form schema · Shared Zod and form validation helpers · `src/lib/client/validators.ts`

### Other components

- **Seedbank**: Next.js app · Full-stack seed economy with games, transfers, profiles, and leaderboard

## Connections

- Seedbank → App shell: uses · Global application shell
- Seedbank → Site layout: contains · Site route group layout
- Seedbank → Login: entry · Unauthenticated entry point
- Seedbank → Dashboard: routes to · Main authenticated hub
- Seedbank → Games: contains · Browser game experience
- Seedbank → Leaderboard: exposes · Balance rankings view
- Seedbank → Profile: exposes · User profile and history view
- Seedbank → Transfer: exposes · Transfer workflow page
- Seedbank → Steal: exposes · Steal workflow page
- Site layout → Navbar: uses · Shared navigation shell
- Site layout → UI primitives: renders with · Reusable UI primitives
- Login → Auth API: calls · Submit credentials and register users
- Dashboard → Daily API: calls · Claim daily reward actions
- Games → Play API: calls · Resolve wagers and update balances
- Steal → Steal API: calls · Perform steal action
- Transfer → Transfer API: calls · Send seeds to another user
- Leaderboard → Leaderboard API: reads · Load rank data
- Profile → Users API: reads · Load profile summary and history
- Steal → Users API: reads · Display interaction history
- Transfer → Users API: reads · Display transfer history
- Auth API → API response: uses · Standardized API responses
- Daily API → Services: delegates · Business logic lives in services
- Play API → Services: delegates · Game resolution and balance mutation
- Steal API → Services: delegates · Steal rules and updates
- Transfer API → Services: delegates · Transfer rules and updates
- Leaderboard API → Services: delegates · Ranking logic
- Users API → Services: delegates · Profile and history reads
- Services → DB layer: queries · Persistence boundary
- DB layer → Schema: persists to · Database schema defines storage
- Schema → Users table: contains · User identity and balance records
- Schema → History table: contains · Audit ledger for balance changes
- Services → History table: appends · Balance-changing actions write audit records
- Services → Server config: uses · Runtime secrets and connection settings
- Login → Client auth: uses · Client-side auth state
- Login → Validators: uses · Form validation
- Games → Validators: uses · Bet and choice validation
- Transfer → Validators: uses · Recipient and amount validation
- Steal → Validators: uses · Target validation
- Docs API → API response: uses · Docs route response shaping
