# marku011/ecoclan architecture

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

- Interactive diagram: https://gitdiagram.com/marku011/ecoclan
- Repository: https://github.com/marku011/ecoclan

## Overview

EcoClan is a cross-platform sustainability app with member and admin experiences, backed by Supabase, plus embedded recycling-station firmware. Members sign in, track household activity, redeem rewards, and use QR passes for deposits and event check-ins. Admins manage claims, events, attendance, and community content. The graph preserves these documented capabilities; detailed wiring is strongest for claim updates, attendance, notifications, and station sorting, since only selected source excerpts were provided.

Main entry points: [`src/components/admin/claimsService.ts`](https://github.com/marku011/ecoclan/blob/main/src/components/admin/claimsService.ts) (Claims service), [`src/app/screens/home.tsx`](https://github.com/marku011/ecoclan/blob/main/src/app/screens/home.tsx) (Member home), [`firmware/EcoClanStation/sort_controller.cpp`](https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/sort_controller.cpp) (Sort controller), [`src/lib/smartNotificationApi.ts`](https://github.com/marku011/ecoclan/blob/main/src/lib/smartNotificationApi.ts) (Notification API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_member["Member app"]
  node_auth["Login and registration<br/>[login_page.tsx]"]
  node_registration["Registration"]
  node_home["Member home<br/>[home.tsx]"]
  node_rewards["Rewards and cart<br/>[rewards.tsx]"]
  node_purchases["Purchase tracking<br/>[purchases.tsx]"]
  node_notifications["Notifications<br/>[notifications.tsx]"]
  node_member_qr["Member QR pass<br/>[qr.tsx]"]
  node_events["Member events<br/>[events.tsx]"]
  node_explore["Explore content<br/>[explore.tsx]"]
end

subgraph group_admin["Admin operations"]
  node_admin_dash["Admin dashboard<br/>[dashboard.tsx]"]
  node_admin_rewards["Reward administration<br/>[rewards.tsx]"]
  node_admin_events["Event administration<br/>[events.tsx]"]
  node_admin_households["Household management<br/>[household.tsx]"]
  node_admin_reports["Reports and analytics<br/>[reports.tsx]"]
end

subgraph group_shared["Shared services"]
  node_entry["App entry<br/>[index.tsx]"]
  node_claims["Claims service<br/>[claimsService.ts]"]
  node_attendance["Attendance service"]
  node_notification_api["Notification API"]
  node_deposit_session["Deposit sessions"]
end

subgraph group_station["Station firmware"]
  node_station_sort["Sort controller"]
  node_station_sensors["Sorting sensors<br/>[sort_sensors.cpp]"]
  node_station_sorter["Sorter logic<br/>[sort_sorter.cpp]"]
  node_station_gate["Sort gate<br/>[sort_gate.cpp]"]
  node_station_deposit["Deposit handling"]
  node_station_backend["Station backend client"]
end

node_member(("Members"))
node_admin_user(("Admin / staff"))
node_supabase[("Supabase")]

node_member -->|"opens app"| node_entry
node_admin_user -->|"opens app"| node_entry
node_entry -->|"routes unauthenticated"| node_auth
node_auth -->|"routes members"| node_home
node_auth -->|"routes admins / staff"| node_admin_dash
node_member -->|"registers"| node_registration
node_home -->|"opens rewards"| node_rewards
node_home -->|"opens events"| node_events
node_home -->|"opens explore"| node_explore
node_rewards -->|"redeems rewards"| node_claims
node_purchases -->|"loads purchases"| node_claims
node_claims -->|"reads / updates claims"| node_supabase
node_admin_rewards -->|"manages claims"| node_claims
node_claims -->|"notifies status changes"| node_notification_api
node_notification_api -->|"stores notifications"| node_supabase
node_notifications -->|"loads and marks read"| node_notification_api
node_notifications -->|"subscribes to changes"| node_supabase
node_member_qr -->|"starts deposit"| node_deposit_session
node_deposit_session -->|"creates session"| node_supabase
node_events -->|"presents check-in pass"| node_member_qr
node_admin_events -->|"records scans"| node_attendance
node_attendance -->|"reads schedules and saves scans"| node_supabase
node_attendance -->|"notifies attendance"| node_notification_api
node_admin_dash -->|"opens household tools"| node_admin_households
node_admin_dash -->|"opens reports"| node_admin_reports
node_station_deposit -->|"ticks sorting"| node_station_sort
node_station_sort -->|"updates sensors"| node_station_sensors
node_station_sort -->|"updates sorter"| node_station_sorter
node_station_sort -->|"controls gate"| node_station_gate
node_station_deposit -->|"submits deposit data"| node_station_backend
node_station_backend -.->|"sends station data"| node_supabase

click node_entry "https://github.com/marku011/ecoclan/blob/main/src/app/index.tsx"
click node_auth "https://github.com/marku011/ecoclan/blob/main/src/app/auth/login_page.tsx"
click node_registration "https://github.com/marku011/ecoclan/blob/main/src/app/auth/registration_page.tsx"
click node_home "https://github.com/marku011/ecoclan/blob/main/src/app/screens/home.tsx"
click node_rewards "https://github.com/marku011/ecoclan/blob/main/src/app/screens/rewards.tsx"
click node_purchases "https://github.com/marku011/ecoclan/blob/main/src/app/screens/purchases.tsx"
click node_notifications "https://github.com/marku011/ecoclan/blob/main/src/app/screens/notifications.tsx"
click node_member_qr "https://github.com/marku011/ecoclan/blob/main/src/app/screens/qr.tsx"
click node_events "https://github.com/marku011/ecoclan/blob/main/src/app/screens/events.tsx"
click node_explore "https://github.com/marku011/ecoclan/blob/main/src/app/screens/explore.tsx"
click node_admin_dash "https://github.com/marku011/ecoclan/blob/main/src/app/admin/dashboard.tsx"
click node_admin_rewards "https://github.com/marku011/ecoclan/blob/main/src/app/admin/rewards.tsx"
click node_admin_events "https://github.com/marku011/ecoclan/blob/main/src/app/admin/events.tsx"
click node_admin_households "https://github.com/marku011/ecoclan/blob/main/src/app/admin/household.tsx"
click node_admin_reports "https://github.com/marku011/ecoclan/blob/main/src/app/admin/reports.tsx"
click node_claims "https://github.com/marku011/ecoclan/blob/main/src/components/admin/claimsService.ts"
click node_attendance "https://github.com/marku011/ecoclan/blob/main/src/lib/eventAttendanceService.ts"
click node_notification_api "https://github.com/marku011/ecoclan/blob/main/src/lib/smartNotificationApi.ts"
click node_deposit_session "https://github.com/marku011/ecoclan/blob/main/src/lib/depositSessionService.ts"
click node_station_sort "https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/sort_controller.cpp"
click node_station_sensors "https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/sort_sensors.cpp"
click node_station_sorter "https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/sort_sorter.cpp"
click node_station_gate "https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/sort_gate.cpp"
click node_station_deposit "https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/deposit_handler.cpp"
click node_station_backend "https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/supabase_client.cpp"

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_auth,node_registration,node_home,node_rewards,node_purchases,node_notifications,node_member_qr,node_events,node_explore toneBlue
class node_admin_dash,node_admin_rewards,node_admin_events,node_admin_households,node_admin_reports,node_supabase toneAmber
class node_entry,node_claims,node_attendance,node_notification_api,node_deposit_session toneMint
class node_station_sort,node_station_sensors,node_station_sorter,node_station_gate,node_station_deposit,node_station_backend toneRose
class node_member,node_admin_user toneIndigo
```

## Components

### Member app

- [Login and registration](https://github.com/marku011/ecoclan/blob/main/src/app/auth/login_page.tsx): `src/app/auth/login_page.tsx`
- [Registration](https://github.com/marku011/ecoclan/blob/main/src/app/auth/registration_page.tsx): `src/app/auth/registration_page.tsx`
- [Member home](https://github.com/marku011/ecoclan/blob/main/src/app/screens/home.tsx): `src/app/screens/home.tsx`
- [Rewards and cart](https://github.com/marku011/ecoclan/blob/main/src/app/screens/rewards.tsx): `src/app/screens/rewards.tsx`
- [Purchase tracking](https://github.com/marku011/ecoclan/blob/main/src/app/screens/purchases.tsx): `src/app/screens/purchases.tsx`
- [Notifications](https://github.com/marku011/ecoclan/blob/main/src/app/screens/notifications.tsx): `src/app/screens/notifications.tsx`
- [Member QR pass](https://github.com/marku011/ecoclan/blob/main/src/app/screens/qr.tsx): `src/app/screens/qr.tsx`
- [Member events](https://github.com/marku011/ecoclan/blob/main/src/app/screens/events.tsx): `src/app/screens/events.tsx`
- [Explore content](https://github.com/marku011/ecoclan/blob/main/src/app/screens/explore.tsx): `src/app/screens/explore.tsx`

### Admin operations

- [Admin dashboard](https://github.com/marku011/ecoclan/blob/main/src/app/admin/dashboard.tsx): `src/app/admin/dashboard.tsx`
- [Reward administration](https://github.com/marku011/ecoclan/blob/main/src/app/admin/rewards.tsx): `src/app/admin/rewards.tsx`
- [Event administration](https://github.com/marku011/ecoclan/blob/main/src/app/admin/events.tsx): `src/app/admin/events.tsx`
- [Household management](https://github.com/marku011/ecoclan/blob/main/src/app/admin/household.tsx): `src/app/admin/household.tsx`
- [Reports and analytics](https://github.com/marku011/ecoclan/blob/main/src/app/admin/reports.tsx): `src/app/admin/reports.tsx`

### Shared services

- [App entry](https://github.com/marku011/ecoclan/blob/main/src/app/index.tsx): `src/app/index.tsx`
- [Claims service](https://github.com/marku011/ecoclan/blob/main/src/components/admin/claimsService.ts): `src/components/admin/claimsService.ts`
- [Attendance service](https://github.com/marku011/ecoclan/blob/main/src/lib/eventAttendanceService.ts): `src/lib/eventAttendanceService.ts`
- [Notification API](https://github.com/marku011/ecoclan/blob/main/src/lib/smartNotificationApi.ts): `src/lib/smartNotificationApi.ts`
- [Deposit sessions](https://github.com/marku011/ecoclan/blob/main/src/lib/depositSessionService.ts): `src/lib/depositSessionService.ts`

### Station firmware

- [Sort controller](https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/sort_controller.cpp): `firmware/EcoClanStation/sort_controller.cpp`
- [Sorting sensors](https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/sort_sensors.cpp): `firmware/EcoClanStation/sort_sensors.cpp`
- [Sorter logic](https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/sort_sorter.cpp): `firmware/EcoClanStation/sort_sorter.cpp`
- [Sort gate](https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/sort_gate.cpp): `firmware/EcoClanStation/sort_gate.cpp`
- [Deposit handling](https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/deposit_handler.cpp): `firmware/EcoClanStation/deposit_handler.cpp`
- [Station backend client](https://github.com/marku011/ecoclan/blob/main/firmware/EcoClanStation/supabase_client.cpp): `firmware/EcoClanStation/supabase_client.cpp`

### Other components

- **Members**
- **Admin / staff**
- **Supabase**

## Connections

- Members → App entry: opens app
- Admin / staff → App entry: opens app
- App entry → Login and registration: routes unauthenticated
- Login and registration → Member home: routes members
- Login and registration → Admin dashboard: routes admins / staff
- Members → Registration: registers
- Member home → Rewards and cart: opens rewards
- Member home → Member events: opens events
- Member home → Explore content: opens explore
- Rewards and cart → Claims service: redeems rewards
- Purchase tracking → Claims service: loads purchases
- Claims service → Supabase: reads / updates claims
- Reward administration → Claims service: manages claims
- Claims service → Notification API: notifies status changes
- Notification API → Supabase: stores notifications
- Notifications → Notification API: loads and marks read
- Notifications → Supabase: subscribes to changes
- Member QR pass → Deposit sessions: starts deposit
- Deposit sessions → Supabase: creates session
- Member events → Member QR pass: presents check-in pass
- Event administration → Attendance service: records scans
- Attendance service → Supabase: reads schedules and saves scans
- Attendance service → Notification API: notifies attendance
- Admin dashboard → Household management: opens household tools
- Admin dashboard → Reports and analytics: opens reports
- Deposit handling → Sort controller: ticks sorting
- Sort controller → Sorting sensors: updates sensors
- Sort controller → Sorter logic: updates sorter
- Sort controller → Sort gate: controls gate
- Deposit handling → Station backend client: submits deposit data
- Station backend client → Supabase: sends station data