# lanczu1/ecobud architecture

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

- Interactive diagram: https://gitdiagram.com/lanczu1/ecobud
- Repository: https://github.com/lanczu1/ecobud

## Overview

ECOBUD is a sustainability-learning and community-action product: members use the mobile app to authenticate, learn, complete challenges, join events, and exchange items; the API handles domain operations and persistence, while administrators manage content and users through a web dashboard. The README also documents public transparency, offline mobile synchronization, and Supabase-powered realtime presence. The graph preserves these major capabilities; some links are documented at product level because their individual route or screen implementations were not sampled.

Main entry points: [`apps/api/src/index.ts`](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/index.ts) (Express API), [`apps/api/src/routes/challengeRoutes.ts`](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/routes/challengeRoutes.ts) (Challenges), [`apps/mobile/src/shared/api/ecobudApi.ts`](https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/shared/api/ecobudApi.ts) (Mobile API client), [`apps/mobile/src/app/EcoBudApp.tsx`](https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/app/EcoBudApp.tsx) (Mobile app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Product clients"]
  node_mobile["Mobile app<br/>[EcoBudApp.tsx]"]
  node_mobile_auth["Mobile auth<br/>[AuthView.tsx]"]
  node_mobile_home["Home dashboard"]
  node_mobile_swap["Swap marketplace<br/>[swapService.ts]"]
  node_mobile_api["Mobile API client<br/>[ecobudApi.ts]"]
  node_offline["Offline sync"]
  node_admin["Admin dashboard<br/>[App.tsx]"]
  node_admin_api["Admin API client<br/>[adminApi.ts]"]
  node_admin_pages["Admin management<br/>[Challenges.tsx]"]
  node_public_site["Public web app<br/>[App.tsx]"]
end

subgraph group_api["API and domain"]
  node_api["Express API<br/>[index.ts]"]
  node_auth["Authentication<br/>[authRoutes.ts]"]
  node_tokens["Token service<br/>[tokenService.ts]"]
  node_challenges["Challenges<br/>[challengeRoutes.ts]"]
  node_lessons["Learning<br/>[LearnService.ts]"]
  node_events["Events<br/>[eventController.ts]"]
  node_swaps["Give and Get<br/>[swapService.ts]"]
  node_transparency["Transparency"]
  node_admin_domain["Admin operations<br/>[adminController.ts]"]
  node_notifications["Notifications"]
  node_presence["Presence queries"]
end

subgraph group_state["Persistence and realtime"]
  node_database[("PostgreSQL")]
  node_prisma["Prisma client<br/>[prismaClient.ts]"]
  node_realtime["Supabase realtime"]
end

subgraph group_external["External services"]
  node_supabase["Supabase"]
  node_firebase["Firebase messaging"]
end

node_member(("Member"))

node_member -->|"uses"| node_mobile
node_member -->|"visits"| node_public_site
node_mobile -->|"authenticates"| node_mobile_auth
node_mobile -->|"shows dashboard"| node_mobile_home
node_mobile_home -->|"requests data"| node_mobile_api
node_mobile_swap -->|"calls API"| node_mobile_api
node_mobile_home -->|"syncs offline work"| node_offline
node_mobile_api -->|"sends API requests"| node_api
node_admin -->|"routes sections"| node_admin_pages
node_admin -->|"imports client"| node_admin_api
node_admin_api -->|"sends API requests"| node_api
node_api -.->|"routes authentication"| node_auth
node_auth -->|"uses tokens"| node_tokens
node_api -.->|"routes challenges"| node_challenges
node_challenges -->|"reads and writes"| node_database
node_challenges -->|"uses client"| node_prisma
node_challenges -.->|"admin manages"| node_admin_domain
node_api -.->|"provides learning"| node_lessons
node_api -.->|"provides events"| node_events
node_api -.->|"provides exchanges"| node_swaps
node_api -.->|"provides transparency"| node_transparency
node_admin_pages -->|"uses API client"| node_admin_api
node_admin_domain -->|"reads and writes"| node_database
node_admin_domain -->|"uses client"| node_prisma
node_notifications -->|"publishes updates"| node_realtime
node_notifications -->|"sends messages"| node_firebase
node_presence -->|"queries presence"| node_database
node_presence -.->|"supports live sync"| node_supabase
node_realtime -->|"uses realtime layer"| node_supabase
node_mobile_api -->|"configures realtime"| node_supabase

click node_mobile "https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/app/EcoBudApp.tsx"
click node_mobile_auth "https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/features/auth/AuthView.tsx"
click node_mobile_home "https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/app/hooks/useHomeDashboard.ts"
click node_mobile_swap "https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/features/giveAndGet/swapService.ts"
click node_mobile_api "https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/shared/api/ecobudApi.ts"
click node_offline "https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/shared/offline/offlineSyncService.ts"
click node_admin "https://github.com/lanczu1/ecobud/blob/main/apps/web/src/App.tsx"
click node_admin_api "https://github.com/lanczu1/ecobud/blob/main/apps/web/src/utils/adminApi.ts"
click node_admin_pages "https://github.com/lanczu1/ecobud/blob/main/apps/web/src/components/admin/pages/Challenges.tsx"
click node_public_site "https://github.com/lanczu1/ecobud/blob/main/apps/landing/src/App.tsx"
click node_api "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/index.ts"
click node_auth "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/routes/authRoutes.ts"
click node_tokens "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/security/tokenService.ts"
click node_challenges "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/routes/challengeRoutes.ts"
click node_lessons "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/LearnService.ts"
click node_events "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/controllers/eventController.ts"
click node_swaps "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/swapService.ts"
click node_transparency "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/TransparencyLedgerService.ts"
click node_admin_domain "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/controllers/adminController.ts"
click node_notifications "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/notificationService.ts"
click node_presence "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/presenceQueryService.ts"
click node_prisma "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/prismaClient.ts"
click node_realtime "https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/supabaseRealtimeService.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_mobile,node_mobile_auth,node_mobile_home,node_mobile_swap,node_mobile_api,node_offline,node_admin,node_admin_api,node_admin_pages,node_public_site toneBlue
class node_api,node_auth,node_tokens,node_challenges,node_lessons,node_events,node_swaps,node_transparency,node_admin_domain,node_notifications,node_presence toneAmber
class node_database,node_prisma,node_realtime toneMint
class node_supabase,node_firebase toneRose
class node_member toneIndigo
```

## Components

### Product clients

- [Mobile app](https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/app/EcoBudApp.tsx): `apps/mobile/src/app/EcoBudApp.tsx`
- [Mobile auth](https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/features/auth/AuthView.tsx): `apps/mobile/src/features/auth/AuthView.tsx`
- [Home dashboard](https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/app/hooks/useHomeDashboard.ts): `apps/mobile/src/app/hooks/useHomeDashboard.ts`
- [Swap marketplace](https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/features/giveAndGet/swapService.ts): `apps/mobile/src/features/giveAndGet/swapService.ts`
- [Mobile API client](https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/shared/api/ecobudApi.ts): `apps/mobile/src/shared/api/ecobudApi.ts`
- [Offline sync](https://github.com/lanczu1/ecobud/blob/main/apps/mobile/src/shared/offline/offlineSyncService.ts): `apps/mobile/src/shared/offline/offlineSyncService.ts`
- [Admin dashboard](https://github.com/lanczu1/ecobud/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Admin API client](https://github.com/lanczu1/ecobud/blob/main/apps/web/src/utils/adminApi.ts): `apps/web/src/utils/adminApi.ts`
- [Admin management](https://github.com/lanczu1/ecobud/blob/main/apps/web/src/components/admin/pages/Challenges.tsx): `apps/web/src/components/admin/pages/Challenges.tsx`
- [Public web app](https://github.com/lanczu1/ecobud/blob/main/apps/landing/src/App.tsx): `apps/landing/src/App.tsx`

### API and domain

- [Express API](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/index.ts): `apps/api/src/index.ts`
- [Authentication](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/routes/authRoutes.ts): `apps/api/src/routes/authRoutes.ts`
- [Token service](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/security/tokenService.ts): `apps/api/src/security/tokenService.ts`
- [Challenges](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/routes/challengeRoutes.ts): `apps/api/src/routes/challengeRoutes.ts`
- [Learning](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/LearnService.ts): `apps/api/src/services/LearnService.ts`
- [Events](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/controllers/eventController.ts): `apps/api/src/controllers/eventController.ts`
- [Give and Get](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/swapService.ts): `apps/api/src/services/swapService.ts`
- [Transparency](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/TransparencyLedgerService.ts): `apps/api/src/services/TransparencyLedgerService.ts`
- [Admin operations](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/controllers/adminController.ts): `apps/api/src/controllers/adminController.ts`
- [Notifications](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/notificationService.ts): `apps/api/src/services/notificationService.ts`
- [Presence queries](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/presenceQueryService.ts): `apps/api/src/services/presenceQueryService.ts`

### Persistence and realtime

- **PostgreSQL**
- [Prisma client](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/prismaClient.ts): `apps/api/src/prismaClient.ts`
- [Supabase realtime](https://github.com/lanczu1/ecobud/blob/main/apps/api/src/services/supabaseRealtimeService.ts): `apps/api/src/services/supabaseRealtimeService.ts`

### External services

- **Supabase**
- **Firebase messaging**

### Other components

- **Member**

## Connections

- Member → Mobile app: uses
- Member → Public web app: visits
- Mobile app → Mobile auth: authenticates
- Mobile app → Home dashboard: shows dashboard (evidence: `apps/mobile/src/app/hooks/useHomeDashboard.ts`)
- Home dashboard → Mobile API client: requests data (evidence: `apps/mobile/src/app/hooks/useHomeDashboard.ts`)
- Swap marketplace → Mobile API client: calls API (evidence: `apps/mobile/src/features/giveAndGet/swapService.ts`)
- Home dashboard → Offline sync: syncs offline work (evidence: `apps/mobile/src/app/hooks/useHomeDashboard.ts`)
- Mobile API client → Express API: sends API requests
- Admin dashboard → Admin management: routes sections (evidence: `apps/web/src/App.tsx`)
- Admin dashboard → Admin API client: imports client (evidence: `apps/web/src/App.tsx`)
- Admin API client → Express API: sends API requests
- Express API → Authentication: routes authentication
- Authentication → Token service: uses tokens (evidence: `apps/api/src/routes/authRoutes.ts`)
- Express API → Challenges: routes challenges
- Challenges → PostgreSQL: reads and writes (evidence: `apps/api/src/routes/challengeRoutes.ts`)
- Challenges → Prisma client: uses client (evidence: `apps/api/src/routes/challengeRoutes.ts`)
- Challenges → Admin operations: admin manages
- Express API → Learning: provides learning
- Express API → Events: provides events
- Express API → Give and Get: provides exchanges
- Express API → Transparency: provides transparency
- Admin management → Admin API client: uses API client (evidence: `apps/web/src/components/admin/pages/Challenges.tsx`)
- Admin operations → PostgreSQL: reads and writes (evidence: `apps/api/src/controllers/adminController.ts`)
- Admin operations → Prisma client: uses client (evidence: `apps/api/src/controllers/adminController.ts`)
- Notifications → Supabase realtime: publishes updates (evidence: `apps/api/src/services/notificationService.ts`)
- Notifications → Firebase messaging: sends messages (evidence: `apps/api/src/services/notificationService.ts`)
- Presence queries → PostgreSQL: queries presence (evidence: `apps/api/src/services/presenceQueryService.ts`)
- Presence queries → Supabase: supports live sync
- Supabase realtime → Supabase: uses realtime layer
- Mobile API client → Supabase: configures realtime
