How bnjmzzn/seedbank works
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: services Services · login/page.tsx Login · transfer/page.tsx Transfer · steal/page.tsx Steal
Components 29
Site UI
Authenticated pages and client-side game flows
- App shell · Global site layout and navigation shell
src/app/layout.tsx - Site layout · Authenticated site wrapper for dashboard and feature pages
src/app/(site)/layout.tsx - Login · Authentication entry point with onboarding content
src/app/login/page.tsx - Dashboard · Authenticated landing page linking to games and account actions
src/app/(site)/dashboard/page.tsx - Games · Browser-facing game pages for wager setup and result display
src/app/(site)/games - Leaderboard · Rankings view based on user balances
src/app/(site)/leaderboard/page.tsx - Profile · User summary and activity history view
src/app/(site)/profile/[username]/page.tsx - Transfer · Send seeds to another user and review transfer history
src/app/(site)/transfer/page.tsx - Steal · 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 · Login and registration endpoints
src/app/(api)/api/auth - Daily API · Daily reward claim endpoint
src/app/(api)/api/daily/route.ts - Play API · Resolves game outcomes and balance changes
src/app/(api)/api/play/route.ts - Steal API · Steal action endpoint
src/app/(api)/api/steal/route.ts - Transfer API · Seed transfer endpoint
src/app/(api)/api/transfer/route.ts - Leaderboard API · Rank retrieval endpoint
src/app/(api)/api/leaderboard/route.ts - Users API · Profile and history lookup endpoints
src/app/(api)/api/users - Docs API · Published API documentation endpoint
src/app/(api)/api/docs/route.ts
Server Core
Shared validation, response shaping, services, and database access
- API response · Shared response shaping and normalization
src/lib/server/api/response.ts - Services · Business rules for auth-adjacent flows, games, transfers, leaderboard, and users
src/lib/server/services - DB layer · Direct database queries and mutations
src/lib/server/db - Server config · Server-side environment and auth configuration
src/lib/server/config.ts
Data Model
Persistent schema and audit trail
- Schema · users and history tables with balance ledger semantics
database/schema.sql - Users table · Identity, credentials, balance, and timestamps
database/schema.sql - History table · Per-user balance change audit trail with reasons and metadata
database/schema.sql
Shared UI
Reusable client-facing components and helpers
- UI primitives · Reusable shared components used across pages
src/components/ui - Navbar · Top-level navigation for the app
src/components/shared/Navbar.tsx - Client auth · Browser auth state and token helpers
src/lib/client/auth.ts - Validators · Shared Zod and form validation helpers
src/lib/client/validators.ts
Other components
- Seedbank · Full-stack seed economy with games, transfers, profiles, and leaderboard
Connections 39
- 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