# aakashreddy-ui/digital-heroes architecture

> Architecture diagram of the GitHub repository aakashreddy-ui/digital-heroes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aakashreddy-ui/digital-heroes
- Repository: https://github.com/aakashreddy-ui/digital-heroes

## Overview

Digital Heroes combines a public charity-first Stableford score platform with subscriber and administrator workflows. Users discover charities, sign up, subscribe, record scores, choose a charity allocation, and enter monthly draws; winners submit proof for verification and payout. Administrators manage users, subscriptions, charities, draws, winners, and analytics. The documented server layers requests through routes, controllers, services, and repositories. The excerpts show draw simulation/publication and proof handling directly; other domain wiring is represented only at the documented layer level.

Main entry points: [`server/src/controllers`](https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/server/src/controllers) (Request controllers), [`server/src/repositories`](https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/server/src/repositories) (Domain repositories), [`client/src/App.tsx`](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/client/src/App.tsx) (Route shell), [`server/src/routes/index.ts`](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/routes/index.ts) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["Route shell<br/>[App.tsx]"]
  node_public["Public pages"]
  node_memberui["Member dashboard"]
  node_adminui["Admin console"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and access"]
  node_api_routes["API routes<br/>[index.ts]"]
  node_auth_gate["Auth and roles<br/>[auth.ts]"]
  node_controllers["Request controllers"]
end

subgraph group_domain["Platform workflows"]
  node_auth["Identity<br/>[authService.ts]"]
  node_scores["Score management<br/>[scoreService.ts]"]
  node_charities["Charity allocation<br/>[charityService.ts]"]
  node_donations["Independent donations<br/>[donationService.ts]"]
  node_subscriptions["Subscriptions"]
  node_draw_engine["Draw lifecycle"]
  node_prize_pool["Prize calculation"]
  node_winners["Winner verification<br/>[winnerService.ts]"]
  node_analytics["Analytics"]
end

subgraph group_data["Persistence and files"]
  node_repositories["Domain repositories"]
  node_database[("Local database<br/>[index.ts]")]
  node_proof_storage["Proof storage<br/>[storage.ts]"]
end

subgraph group_integrations["External services"]
  node_stripe["Stripe payments"]
  node_supabase["Supabase storage"]
end

node_visitor(("Visitor or member"))
node_admin(("Administrator"))

node_visitor -->|"uses"| node_app
node_admin -->|"uses"| node_app
node_app -->|"routes to"| node_public
node_app -->|"routes to"| node_memberui
node_app -->|"routes to"| node_adminui
node_public -->|"requests data"| node_api_client
node_memberui -->|"requests data"| node_api_client
node_adminui -->|"requests data"| node_api_client
node_api_client -->|"sends requests"| node_api_routes
node_api_routes -->|"protects routes"| node_auth_gate
node_api_routes -->|"dispatches"| node_controllers
node_controllers -->|"calls"| node_auth
node_controllers -->|"calls"| node_scores
node_controllers -->|"calls"| node_charities
node_controllers -->|"calls"| node_donations
node_controllers -->|"calls"| node_subscriptions
node_controllers -->|"simulates or publishes"| node_draw_engine
node_controllers -->|"calls"| node_winners
node_controllers -->|"calls"| node_analytics
node_auth -->|"reads and writes"| node_repositories
node_scores -->|"reads and writes"| node_repositories
node_charities -->|"reads and writes"| node_repositories
node_donations -->|"reads and writes"| node_repositories
node_subscriptions -->|"reads and writes"| node_repositories
node_draw_engine -->|"reads and writes"| node_repositories
node_draw_engine -->|"calculates pools"| node_prize_pool
node_winners -->|"reads and writes"| node_repositories
node_analytics -->|"queries"| node_repositories
node_repositories -->|"queries"| node_database
node_controllers -->|"stores or signs proofs"| node_proof_storage
node_subscriptions -.->|"creates checkout"| node_stripe
node_stripe -.->|"sends webhooks"| node_api_routes
node_proof_storage -.->|"uploads or signs"| node_supabase

click node_app "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/client/src/App.tsx"
click node_public "https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/client/src/pages/public"
click node_memberui "https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/client/src/pages/dashboard"
click node_adminui "https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/client/src/pages/admin"
click node_api_client "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/client/src/api/client.ts"
click node_api_routes "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/routes/index.ts"
click node_auth_gate "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/middleware/auth.ts"
click node_controllers "https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/server/src/controllers"
click node_auth "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/authService.ts"
click node_scores "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/scoreService.ts"
click node_charities "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/charityService.ts"
click node_donations "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/donationService.ts"
click node_subscriptions "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/subscriptionService.ts"
click node_draw_engine "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/drawEngineService.ts"
click node_prize_pool "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/prizePoolService.ts"
click node_winners "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/winnerService.ts"
click node_analytics "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/controllers/analyticsController.ts"
click node_repositories "https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/server/src/repositories"
click node_database "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/db/index.ts"
click node_proof_storage "https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/utils/storage.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_app,node_public,node_memberui,node_adminui,node_api_client toneBlue
class node_api_routes,node_auth_gate,node_controllers toneAmber
class node_auth,node_scores,node_charities,node_donations,node_subscriptions,node_draw_engine,node_prize_pool,node_winners,node_analytics toneMint
class node_repositories,node_database,node_proof_storage toneRose
class node_stripe,node_supabase,node_visitor,node_admin toneIndigo
```

## Components

### Web application

- [Route shell](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/client/src/App.tsx): `client/src/App.tsx`
- [Public pages](https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/client/src/pages/public): `client/src/pages/public`
- [Member dashboard](https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/client/src/pages/dashboard): `client/src/pages/dashboard`
- [Admin console](https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/client/src/pages/admin): `client/src/pages/admin`
- [API client](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/client/src/api/client.ts): `client/src/api/client.ts`

### API and access

- [API routes](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/routes/index.ts): `server/src/routes/index.ts`
- [Auth and roles](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/middleware/auth.ts): `server/src/middleware/auth.ts`
- [Request controllers](https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/server/src/controllers): `server/src/controllers`

### Platform workflows

- [Identity](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/authService.ts): `server/src/services/authService.ts`
- [Score management](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/scoreService.ts): `server/src/services/scoreService.ts`
- [Charity allocation](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/charityService.ts): `server/src/services/charityService.ts`
- [Independent donations](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/donationService.ts): `server/src/services/donationService.ts`
- [Subscriptions](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/subscriptionService.ts): `server/src/services/subscriptionService.ts`
- [Draw lifecycle](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/drawEngineService.ts): `server/src/services/drawEngineService.ts`
- [Prize calculation](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/prizePoolService.ts): `server/src/services/prizePoolService.ts`
- [Winner verification](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/services/winnerService.ts): `server/src/services/winnerService.ts`
- [Analytics](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/controllers/analyticsController.ts): `server/src/controllers/analyticsController.ts`

### Persistence and files

- [Domain repositories](https://github.com/aakashreddy-ui/digital-heroes/tree/main-setup/server/src/repositories): `server/src/repositories`
- [Local database](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/db/index.ts): `server/src/db/index.ts`
- [Proof storage](https://github.com/aakashreddy-ui/digital-heroes/blob/main-setup/server/src/utils/storage.ts): `server/src/utils/storage.ts`

### External services

- **Stripe payments**
- **Supabase storage**

### Other components

- **Visitor or member**
- **Administrator**

## Connections

- Visitor or member → Route shell: uses
- Administrator → Route shell: uses
- Route shell → Public pages: routes to
- Route shell → Member dashboard: routes to
- Route shell → Admin console: routes to
- Public pages → API client: requests data
- Member dashboard → API client: requests data
- Admin console → API client: requests data
- API client → API routes: sends requests
- API routes → Auth and roles: protects routes
- API routes → Request controllers: dispatches
- Request controllers → Identity: calls
- Request controllers → Score management: calls
- Request controllers → Charity allocation: calls
- Request controllers → Independent donations: calls
- Request controllers → Subscriptions: calls
- Request controllers → Draw lifecycle: simulates or publishes
- Request controllers → Winner verification: calls
- Request controllers → Analytics: calls
- Identity → Domain repositories: reads and writes
- Score management → Domain repositories: reads and writes
- Charity allocation → Domain repositories: reads and writes
- Independent donations → Domain repositories: reads and writes
- Subscriptions → Domain repositories: reads and writes
- Draw lifecycle → Domain repositories: reads and writes
- Draw lifecycle → Prize calculation: calculates pools
- Winner verification → Domain repositories: reads and writes
- Analytics → Domain repositories: queries
- Domain repositories → Local database: queries
- Request controllers → Proof storage: stores or signs proofs
- Subscriptions → Stripe payments: creates checkout
- Stripe payments → API routes: sends webhooks
- Proof storage → Supabase storage: uploads or signs