# kemgp/tidetrace architecture

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

- Interactive diagram: https://gitdiagram.com/kemgp/tidetrace
- Repository: https://github.com/kemgp/tidetrace

## Overview

TideTrace is a community conservation app for members to explore approved Traces and Tides, submit Traces for review, and follow moderation updates. The main connected workflow is sign-in, draft submission with optional evidence photos, staff review, and publication or revision; members can then browse saved Traces and lessons. The React client also includes admin and moderator capabilities, while the Node API exposes the persistent workflows over Supabase. Dashboard actions and statistics remain demo-backed. Relationships for unsampled areas reflect README descriptions; source excerpts do not reveal every endpoint-to-database interaction.

Main entry points: [`client/src/context/AppContext.jsx`](https://github.com/kemgp/tidetrace/blob/main/client/src/context/AppContext.jsx) (Session and app state), [`server/src/app.js`](https://github.com/kemgp/tidetrace/blob/main/server/src/app.js) (HTTP API), [`client/src/api/data.js`](https://github.com/kemgp/tidetrace/blob/main/client/src/api/data.js) (Data API client), [`client/src/App.jsx`](https://github.com/kemgp/tidetrace/blob/main/client/src/App.jsx) (App routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Member experience"]
  node_app["App routes<br/>[App.jsx]"]
  node_state["Session and app state<br/>[AppContext.jsx]"]
  node_authui["Sign-in flows"]
  node_authclient["Auth API client<br/>[auth.js]"]
  node_session["Session manager<br/>[session.js]"]
  node_remote["Remote data hook<br/>[useRemoteData.js]"]
  node_remoteui["Loading and errors<br/>[RemoteState.jsx]"]
  node_skeleton["Loading skeletons<br/>[SkeletonLoader.jsx]"]
  node_dataapi["Data API client<br/>[data.js]"]
  node_traces["Trace browsing and drafts"]
  node_photos["Trace photo previews<br/>[TracePhotos.jsx]"]
  node_tides["Tide lessons"]
  node_notifications["Member notifications<br/>[Notifications.jsx]"]
  node_profile["Profile and account"]
  node_demo["Demo dashboard data<br/>[mockData.js]"]
end

subgraph group_review["Staff workflows"]
  node_reviewtraces["Trace review<br/>[ReviewTraces.jsx]"]
  node_reports["Report review<br/>[ManageReports.jsx]"]
  node_admin["Admin management"]
end

subgraph group_api["API services"]
  node_apiapp["HTTP API<br/>[app.js]"]
  node_authroutes["Authentication routes<br/>[auth.js]"]
  node_contentroutes["Content routes<br/>[content.js]"]
  node_staffroutes["Staff routes<br/>[staff.js]"]
  node_mediaroutes["Media routes<br/>[media.js]"]
  node_middleware["Request authentication<br/>[middleware.js]"]
  node_validation["Request validation<br/>[validation.js]"]
end

subgraph group_data["Persistence"]
  node_supabase["Supabase gateway<br/>[supabase.js]"]
  node_postgres[("Supabase PostgreSQL")]
  node_storage[("Supabase Storage")]
  node_supaauth["Supabase Auth"]
end

node_member(("Member"))
node_staff(("Moderator or admin"))

node_member -->|"uses"| node_app
node_staff -->|"uses"| node_app
node_app -->|"provides state"| node_state
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_traces
node_state -->|"authenticates with"| node_authclient
node_state -->|"manages sessions"| node_session
node_state -->|"requests data"| node_dataapi
node_remote -->|"reads through"| node_state
node_remote -->|"reports state"| node_remoteui
node_remoteui -->|"renders"| node_skeleton
node_traces -.->|"loads and saves"| node_dataapi
node_traces -->|"previews evidence"| node_photos
node_tides -.->|"loads lessons"| node_dataapi
node_notifications -->|"uses app state"| node_state
node_state -->|"loads demo data"| node_demo
node_reviewtraces -.->|"reads and decides"| node_dataapi
node_reports -->|"renders evidence"| node_photos
node_admin -.->|"manages content"| node_dataapi
node_apiapp -->|"mounts"| node_authroutes
node_apiapp -->|"mounts"| node_contentroutes
node_apiapp -->|"mounts"| node_staffroutes
node_apiapp -->|"mounts"| node_mediaroutes
node_apiapp -->|"installs"| node_middleware
node_authroutes -->|"authenticates via"| node_supabase
node_authclient -.->|"calls"| node_authroutes
node_dataapi -.->|"calls API"| node_apiapp
node_middleware -->|"creates data client"| node_supabase
node_middleware -.->|"uses"| node_validation
node_supabase -.->|"accesses"| node_supaauth
node_supabase -.->|"reads and writes"| node_postgres
node_mediaroutes -.->|"uploads evidence"| node_storage
node_staffroutes -.->|"moderates records"| node_postgres

click node_app "https://github.com/kemgp/tidetrace/blob/main/client/src/App.jsx"
click node_state "https://github.com/kemgp/tidetrace/blob/main/client/src/context/AppContext.jsx"
click node_authui "https://github.com/kemgp/tidetrace/tree/main/client/src/pages/auth"
click node_authclient "https://github.com/kemgp/tidetrace/blob/main/client/src/api/auth.js"
click node_session "https://github.com/kemgp/tidetrace/blob/main/client/src/api/session.js"
click node_remote "https://github.com/kemgp/tidetrace/blob/main/client/src/hooks/useRemoteData.js"
click node_remoteui "https://github.com/kemgp/tidetrace/blob/main/client/src/components/RemoteState.jsx"
click node_skeleton "https://github.com/kemgp/tidetrace/blob/main/client/src/components/SkeletonLoader.jsx"
click node_dataapi "https://github.com/kemgp/tidetrace/blob/main/client/src/api/data.js"
click node_traces "https://github.com/kemgp/tidetrace/tree/main/client/src/pages/user/traces"
click node_photos "https://github.com/kemgp/tidetrace/blob/main/client/src/components/TracePhotos.jsx"
click node_tides "https://github.com/kemgp/tidetrace/tree/main/client/src/pages/user/tides"
click node_notifications "https://github.com/kemgp/tidetrace/blob/main/client/src/pages/user/notifications/Notifications.jsx"
click node_profile "https://github.com/kemgp/tidetrace/blob/main/client/src/components/ProfileNameForm.jsx"
click node_demo "https://github.com/kemgp/tidetrace/blob/main/client/src/data/mockData.js"
click node_reviewtraces "https://github.com/kemgp/tidetrace/blob/main/client/src/pages/moderator/ReviewTraces.jsx"
click node_reports "https://github.com/kemgp/tidetrace/blob/main/client/src/pages/moderator/ManageReports.jsx"
click node_admin "https://github.com/kemgp/tidetrace/tree/main/client/src/pages/admin"
click node_apiapp "https://github.com/kemgp/tidetrace/blob/main/server/src/app.js"
click node_authroutes "https://github.com/kemgp/tidetrace/blob/main/server/src/routes/auth.js"
click node_contentroutes "https://github.com/kemgp/tidetrace/blob/main/server/src/routes/content.js"
click node_staffroutes "https://github.com/kemgp/tidetrace/blob/main/server/src/routes/staff.js"
click node_mediaroutes "https://github.com/kemgp/tidetrace/blob/main/server/src/routes/media.js"
click node_middleware "https://github.com/kemgp/tidetrace/blob/main/server/src/middleware.js"
click node_validation "https://github.com/kemgp/tidetrace/blob/main/server/src/validation.js"
click node_supabase "https://github.com/kemgp/tidetrace/blob/main/server/src/supabase.js"

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_state,node_authui,node_authclient,node_session,node_remote,node_remoteui,node_skeleton,node_dataapi,node_traces,node_photos,node_tides,node_notifications,node_profile,node_demo toneBlue
class node_reviewtraces,node_reports,node_admin toneAmber
class node_apiapp,node_authroutes,node_contentroutes,node_staffroutes,node_mediaroutes,node_middleware,node_validation toneMint
class node_supabase,node_postgres,node_storage,node_supaauth toneRose
class node_member,node_staff toneIndigo
```

## Components

### Member experience

- [App routes](https://github.com/kemgp/tidetrace/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Session and app state](https://github.com/kemgp/tidetrace/blob/main/client/src/context/AppContext.jsx): `client/src/context/AppContext.jsx`
- [Sign-in flows](https://github.com/kemgp/tidetrace/tree/main/client/src/pages/auth): `client/src/pages/auth`
- [Auth API client](https://github.com/kemgp/tidetrace/blob/main/client/src/api/auth.js): `client/src/api/auth.js`
- [Session manager](https://github.com/kemgp/tidetrace/blob/main/client/src/api/session.js): `client/src/api/session.js`
- [Remote data hook](https://github.com/kemgp/tidetrace/blob/main/client/src/hooks/useRemoteData.js): `client/src/hooks/useRemoteData.js`
- [Loading and errors](https://github.com/kemgp/tidetrace/blob/main/client/src/components/RemoteState.jsx): `client/src/components/RemoteState.jsx`
- [Loading skeletons](https://github.com/kemgp/tidetrace/blob/main/client/src/components/SkeletonLoader.jsx): `client/src/components/SkeletonLoader.jsx`
- [Data API client](https://github.com/kemgp/tidetrace/blob/main/client/src/api/data.js): `client/src/api/data.js`
- [Trace browsing and drafts](https://github.com/kemgp/tidetrace/tree/main/client/src/pages/user/traces): `client/src/pages/user/traces`
- [Trace photo previews](https://github.com/kemgp/tidetrace/blob/main/client/src/components/TracePhotos.jsx): `client/src/components/TracePhotos.jsx`
- [Tide lessons](https://github.com/kemgp/tidetrace/tree/main/client/src/pages/user/tides): `client/src/pages/user/tides`
- [Member notifications](https://github.com/kemgp/tidetrace/blob/main/client/src/pages/user/notifications/Notifications.jsx): `client/src/pages/user/notifications/Notifications.jsx`
- [Profile and account](https://github.com/kemgp/tidetrace/blob/main/client/src/components/ProfileNameForm.jsx): `client/src/components/ProfileNameForm.jsx`
- [Demo dashboard data](https://github.com/kemgp/tidetrace/blob/main/client/src/data/mockData.js): `client/src/data/mockData.js`

### Staff workflows

- [Trace review](https://github.com/kemgp/tidetrace/blob/main/client/src/pages/moderator/ReviewTraces.jsx): `client/src/pages/moderator/ReviewTraces.jsx`
- [Report review](https://github.com/kemgp/tidetrace/blob/main/client/src/pages/moderator/ManageReports.jsx): `client/src/pages/moderator/ManageReports.jsx`
- [Admin management](https://github.com/kemgp/tidetrace/tree/main/client/src/pages/admin): `client/src/pages/admin`

### API services

- [HTTP API](https://github.com/kemgp/tidetrace/blob/main/server/src/app.js): `server/src/app.js`
- [Authentication routes](https://github.com/kemgp/tidetrace/blob/main/server/src/routes/auth.js): `server/src/routes/auth.js`
- [Content routes](https://github.com/kemgp/tidetrace/blob/main/server/src/routes/content.js): `server/src/routes/content.js`
- [Staff routes](https://github.com/kemgp/tidetrace/blob/main/server/src/routes/staff.js): `server/src/routes/staff.js`
- [Media routes](https://github.com/kemgp/tidetrace/blob/main/server/src/routes/media.js): `server/src/routes/media.js`
- [Request authentication](https://github.com/kemgp/tidetrace/blob/main/server/src/middleware.js): `server/src/middleware.js`
- [Request validation](https://github.com/kemgp/tidetrace/blob/main/server/src/validation.js): `server/src/validation.js`

### Persistence

- [Supabase gateway](https://github.com/kemgp/tidetrace/blob/main/server/src/supabase.js): `server/src/supabase.js`
- **Supabase PostgreSQL**
- **Supabase Storage**
- **Supabase Auth**

### Other components

- **Member**
- **Moderator or admin**

## Connections

- Member → App routes: uses (evidence: `README.md`)
- Moderator or admin → App routes: uses (evidence: `README.md`)
- App routes → Session and app state: provides state (evidence: `client/src/App.jsx`)
- App routes → Sign-in flows: routes to (evidence: `client/src/App.jsx`)
- App routes → Trace browsing and drafts: routes to (evidence: `client/src/App.jsx`)
- Session and app state → Auth API client: authenticates with (evidence: `client/src/context/AppContext.jsx`)
- Session and app state → Session manager: manages sessions (evidence: `client/src/context/AppContext.jsx`)
- Session and app state → Data API client: requests data (evidence: `client/src/context/AppContext.jsx`)
- Remote data hook → Session and app state: reads through (evidence: `client/src/hooks/useRemoteData.js`)
- Remote data hook → Loading and errors: reports state (evidence: `client/src/pages/user/tides/Tides.jsx`)
- Loading and errors → Loading skeletons: renders (evidence: `client/src/components/RemoteState.jsx`)
- Trace browsing and drafts → Data API client: loads and saves (evidence: `README.md`)
- Trace browsing and drafts → Trace photo previews: previews evidence (evidence: `client/src/components/TracePhotos.jsx`)
- Tide lessons → Data API client: loads lessons (evidence: `README.md`)
- Member notifications → Session and app state: uses app state (evidence: `client/src/pages/user/notifications/Notifications.jsx`)
- Session and app state → Demo dashboard data: loads demo data (evidence: `client/src/context/AppContext.jsx`)
- Trace review → Data API client: reads and decides (evidence: `README.md`)
- Report review → Trace photo previews: renders evidence (evidence: `client/src/pages/moderator/ManageReports.jsx`)
- Admin management → Data API client: manages content (evidence: `README.md`)
- HTTP API → Authentication routes: mounts (evidence: `server/src/app.js`)
- HTTP API → Content routes: mounts (evidence: `server/src/app.js`)
- HTTP API → Staff routes: mounts (evidence: `server/src/app.js`)
- HTTP API → Media routes: mounts (evidence: `server/src/app.js`)
- HTTP API → Request authentication: installs (evidence: `server/src/app.js`)
- Authentication routes → Supabase gateway: authenticates via (evidence: `server/src/routes/auth.js`)
- Auth API client → Authentication routes: calls (evidence: `README.md`)
- Data API client → HTTP API: calls API (evidence: `README.md`)
- Request authentication → Supabase gateway: creates data client (evidence: `server/src/middleware.js`)
- Request authentication → Request validation: uses (evidence: `server/src/routes/auth.js`)
- Supabase gateway → Supabase Auth: accesses (evidence: `README.md`)
- Supabase gateway → Supabase PostgreSQL: reads and writes (evidence: `README.md`)
- Media routes → Supabase Storage: uploads evidence (evidence: `README.md`)
- Staff routes → Supabase PostgreSQL: moderates records (evidence: `README.md`)
