# ghostmadi/clover architecture

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

- Interactive diagram: https://gitdiagram.com/ghostmadi/clover
- Repository: https://github.com/ghostmadi/clover
- Video tour (about a minute): https://gitdiagram.com/ghostmadi/clover/video

## Overview

Clover combines a web cabinet and public site with a mobile app, supporting social posts and profiles, messaging, booking, attendance, venue planning, resources, and administration. The tree and README establish these product areas, but the sampled source is concentrated in web authentication, admin APIs, and media uploads; links among the unsampled feature modules are therefore omitted. The clearest traced workflow is an authenticated web media upload through a same-origin route, which obtains an upload URL from an Edge Function and sends bytes to R2.

Main entry points: [`web/src/features/admin`](https://github.com/ghostmadi/clover/tree/main/web/src/features/admin) (Admin console), [`web/src/app/api/r2/upload/route.ts`](https://github.com/ghostmadi/clover/blob/main/web/src/app/api/r2/upload/route.ts) (Upload proxy), [`web/src/app/auth`](https://github.com/ghostmadi/clover/tree/main/web/src/app/auth) (Web authentication), [`web/src/app/auth/callback/route.ts`](https://github.com/ghostmadi/clover/blob/main/web/src/app/auth/callback/route.ts) (Auth callback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_social["Social"]
  node_feed["Feed and posts"]
  node_profiles["Profiles and clusters"]
  node_chat["Chat"]
  node_notifications["Notifications"]
end

subgraph group_services["Workspaces"]
  node_booking["Booking"]
  node_attendance["Attendance"]
  node_venue["Venue planning"]
  node_resources["Resources"]
end

subgraph group_platform["Platform services"]
  node_auth["Web authentication"]
  node_auth_callback["Auth callback<br/>[route.ts]"]
  node_r2_client["Media upload client<br/>[r2-storage.ts]"]
  node_upload_route["Upload proxy<br/>[route.ts]"]
  node_upload_url["Upload URL function<br/>[index.ts]"]
  node_r2[("Cloudflare R2")]
  node_supabase[("Supabase services")]
end

subgraph group_admin["Administration"]
  node_admin_ui["Admin console"]
  node_admin_auth["Admin login and registration<br/>[route.ts]"]
  node_admin_support["Support inbox API<br/>[route.ts]"]
  node_admin_analytics["Platform analytics API<br/>[route.ts]"]
  node_quiz_api["Quiz admin API<br/>[route.ts]"]
end

node_user(("User"))

node_user -->|"signs in"| node_auth
node_auth -->|"returns via"| node_auth_callback
node_auth_callback -->|"exchanges code"| node_supabase
node_user -->|"uploads media"| node_r2_client
node_r2_client -->|"posts file"| node_upload_route
node_upload_route -->|"gets upload URL"| node_supabase
node_upload_route -->|"invokes"| node_upload_url
node_upload_route -->|"puts bytes"| node_r2
node_user -->|"browses posts"| node_feed
node_user -->|"views profiles"| node_profiles
node_user -->|"messages"| node_chat
node_user -->|"checks alerts"| node_notifications
node_user -->|"books services"| node_booking
node_user -->|"tracks attendance"| node_attendance
node_user -->|"plans venue"| node_venue
node_user -->|"browses resources"| node_resources
node_user -->|"administers"| node_admin_ui
node_admin_ui -->|"authenticates via"| node_admin_auth
node_admin_ui -->|"manages support"| node_admin_support
node_admin_ui -->|"requests metrics"| node_admin_analytics
node_admin_ui -->|"reviews quiz runs"| node_quiz_api
node_admin_auth -->|"checks admin"| node_supabase
node_admin_support -->|"reads and updates"| node_supabase
node_admin_analytics -->|"queries metrics"| node_supabase
node_quiz_api -->|"queries runs"| node_supabase

click node_feed "https://github.com/ghostmadi/clover/tree/main/web/src/features/feed"
click node_profiles "https://github.com/ghostmadi/clover/tree/main/web/src/features/profile"
click node_chat "https://github.com/ghostmadi/clover/tree/main/web/src/features/chat"
click node_notifications "https://github.com/ghostmadi/clover/tree/main/web/src/features/notifications"
click node_booking "https://github.com/ghostmadi/clover/tree/main/web/src/features/booking"
click node_attendance "https://github.com/ghostmadi/clover/tree/main/web/src/features/attendance"
click node_venue "https://github.com/ghostmadi/clover/tree/main/web/src/features/venue"
click node_resources "https://github.com/ghostmadi/clover/tree/main/web/src/features/resources"
click node_auth "https://github.com/ghostmadi/clover/tree/main/web/src/app/auth"
click node_auth_callback "https://github.com/ghostmadi/clover/blob/main/web/src/app/auth/callback/route.ts"
click node_r2_client "https://github.com/ghostmadi/clover/blob/main/web/src/lib/r2-storage.ts"
click node_upload_route "https://github.com/ghostmadi/clover/blob/main/web/src/app/api/r2/upload/route.ts"
click node_upload_url "https://github.com/ghostmadi/clover/blob/main/supabase/functions/get-upload-url/index.ts"
click node_admin_ui "https://github.com/ghostmadi/clover/tree/main/web/src/features/admin"
click node_admin_auth "https://github.com/ghostmadi/clover/blob/main/web/src/app/api/admin/login/route.ts"
click node_admin_support "https://github.com/ghostmadi/clover/blob/main/web/src/app/api/admin/support/route.ts"
click node_admin_analytics "https://github.com/ghostmadi/clover/blob/main/web/src/app/api/admin/stats/route.ts"
click node_quiz_api "https://github.com/ghostmadi/clover/blob/main/web/src/app/api/admin/honest-quiz/route.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_feed,node_profiles,node_chat,node_notifications,node_user toneBlue
class node_booking,node_attendance,node_venue,node_resources toneAmber
class node_auth,node_auth_callback,node_r2_client,node_upload_route,node_upload_url,node_r2,node_supabase toneMint
class node_admin_ui,node_admin_auth,node_admin_support,node_admin_analytics,node_quiz_api toneRose
```

## Components

### Social

- [Feed and posts](https://github.com/ghostmadi/clover/tree/main/web/src/features/feed): `web/src/features/feed`
- [Profiles and clusters](https://github.com/ghostmadi/clover/tree/main/web/src/features/profile): `web/src/features/profile`
- [Chat](https://github.com/ghostmadi/clover/tree/main/web/src/features/chat): `web/src/features/chat`
- [Notifications](https://github.com/ghostmadi/clover/tree/main/web/src/features/notifications): `web/src/features/notifications`

### Workspaces

- [Booking](https://github.com/ghostmadi/clover/tree/main/web/src/features/booking): `web/src/features/booking`
- [Attendance](https://github.com/ghostmadi/clover/tree/main/web/src/features/attendance): `web/src/features/attendance`
- [Venue planning](https://github.com/ghostmadi/clover/tree/main/web/src/features/venue): `web/src/features/venue`
- [Resources](https://github.com/ghostmadi/clover/tree/main/web/src/features/resources): `web/src/features/resources`

### Platform services

- [Web authentication](https://github.com/ghostmadi/clover/tree/main/web/src/app/auth): `web/src/app/auth`
- [Auth callback](https://github.com/ghostmadi/clover/blob/main/web/src/app/auth/callback/route.ts): `web/src/app/auth/callback/route.ts`
- [Media upload client](https://github.com/ghostmadi/clover/blob/main/web/src/lib/r2-storage.ts): `web/src/lib/r2-storage.ts`
- [Upload proxy](https://github.com/ghostmadi/clover/blob/main/web/src/app/api/r2/upload/route.ts): `web/src/app/api/r2/upload/route.ts`
- [Upload URL function](https://github.com/ghostmadi/clover/blob/main/supabase/functions/get-upload-url/index.ts): `supabase/functions/get-upload-url/index.ts`
- **Cloudflare R2**
- **Supabase services**

### Administration

- [Admin console](https://github.com/ghostmadi/clover/tree/main/web/src/features/admin): `web/src/features/admin`
- [Admin login and registration](https://github.com/ghostmadi/clover/blob/main/web/src/app/api/admin/login/route.ts): `web/src/app/api/admin/login/route.ts`
- [Support inbox API](https://github.com/ghostmadi/clover/blob/main/web/src/app/api/admin/support/route.ts): `web/src/app/api/admin/support/route.ts`
- [Platform analytics API](https://github.com/ghostmadi/clover/blob/main/web/src/app/api/admin/stats/route.ts): `web/src/app/api/admin/stats/route.ts`
- [Quiz admin API](https://github.com/ghostmadi/clover/blob/main/web/src/app/api/admin/honest-quiz/route.ts): `web/src/app/api/admin/honest-quiz/route.ts`

### Other components

- **User**

## Connections

- User → Web authentication: signs in
- Web authentication → Auth callback: returns via
- Auth callback → Supabase services: exchanges code
- User → Media upload client: uploads media
- Media upload client → Upload proxy: posts file
- Upload proxy → Supabase services: gets upload URL
- Upload proxy → Upload URL function: invokes
- Upload proxy → Cloudflare R2: puts bytes
- User → Feed and posts: browses posts
- User → Profiles and clusters: views profiles
- User → Chat: messages
- User → Notifications: checks alerts
- User → Booking: books services
- User → Attendance: tracks attendance
- User → Venue planning: plans venue
- User → Resources: browses resources
- User → Admin console: administers
- Admin console → Admin login and registration: authenticates via
- Admin console → Support inbox API: manages support
- Admin console → Platform analytics API: requests metrics
- Admin console → Quiz admin API: reviews quiz runs
- Admin login and registration → Supabase services: checks admin
- Support inbox API → Supabase services: reads and updates
- Platform analytics API → Supabase services: queries metrics
- Quiz admin API → Supabase services: queries runs