# rawepatj/tidrod architecture

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

- Interactive diagram: https://gitdiagram.com/rawepatj/tidrod
- Repository: https://github.com/rawepatj/tidrod

## Overview

1. This is a two-part monorepo: a Next.js frontend in `front/` and a TypeScript Node backend in `back/`, with `docker-compose.yml` and separate Dockerfiles for local/containerized deployment.

2. The frontend is organized around the Next.js App Router. Routes are split into user-facing flows (`/login`, `/register`, `/forgot-password`, `/reset-password`, `/verify-email`, `/profile`, `/trip/[id]`, `/home`) and an admin area under `/admin` with dedicated pages for users, trips, reports, and logs.

3. The backend is a route-based API. `src/routes/` contains domain modules for `auth`, `users`, `trips`, `messages`, `notifications`, `reports`, `markers`, and `admin`, which suggests the server is the main business-logic boundary and the frontend is mostly a consumer of these endpoints.

4. Authentication and authorization are enforced in middleware, not just in the UI. `middleware/auth.ts` and `middleware/admin.ts` indicate protected user endpoints and a separate admin permission layer, matching the frontend’s normal vs admin split.

5. The app has a strong trip-centric domain model. Frontend components such as `SearchTrip`, `TripForm`, `MyTrips`, `TripRatingsList`, `RateTripModal`, and `ReportModal` imply trip discovery, trip creation/joining, ratings, and moderation/reporting as core workflows.

6. Real-time interaction is a first-class subsystem. `back/src/socket.ts` plus frontend components like `Chat`, `NotificationBell`, and `LobbyBox` point to websocket-driven messaging and live notifications alongside the normal REST API.

7. Persistence is abstracted behind a database layer in `back/src/db.ts`, with startup/bootstrap support in `init-db.ts` and an admin bootstrap script in `src/scripts/make-admin.ts`. This suggests the server owns schema/data initialization and operational setup, rather than the frontend.

8. There is an email-based account lifecycle. `back/src/utils/email.ts` and frontend pages for email verification and password reset imply the backend sends transactional email for registration verification and credential recovery.

9. The frontend contains map and location-oriented UI. `Map.tsx`, `AutocompleteInput.tsx`, and the presence of `public/osm_liberty.json` indicate map rendering/styling and location search as part of trip creation or discovery.

10. The admin console is a separate operational surface, not just a hidden page. It has its own layout and sidebar, and is backed by admin-specific backend routes and middleware, so it should be treated as a distinct subsystem for moderation and oversight.

11. Shared client-side infrastructure includes `SessionProvider`, toasts, skeleton/loading states, and reusable UI primitives. These are supporting layers around the main feature flows rather than separate domains.

12. Operationally, the backend includes logging (`utils/logger.ts`) and the repo is set up for containerized deployment, making the likely request path: browser → Next.js UI → backend REST/socket API → database/storage/email services.

Main entry points: [`front/app`](https://github.com/rawepatj/tidrod/tree/main/front/app) (App Router), [`back/src/index.ts`](https://github.com/rawepatj/tidrod/blob/main/back/src/index.ts) (API Server), [`back/src/routes`](https://github.com/rawepatj/tidrod/tree/main/back/src/routes) (Route Modules), [`front/lib/api.ts`](https://github.com/rawepatj/tidrod/blob/main/front/lib/api.ts) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_front_app["App Router<br/>nextjs routes"]
  node_front_auth["Auth Pages<br/>user flows"]
  node_front_home["Home Feed<br/>trip discovery"]
  node_front_trip["Trip Detail<br/>trip page"]
  node_front_profile["Profile<br/>account page"]
  node_front_admin["Admin Console<br/>ops UI"]
  node_front_ui["UI Components<br/>shared components"]
  node_front_api["API Client<br/>browser client<br/>[api.ts]"]
  node_front_session["Session State<br/>client state"]
  node_front_map["Map UI<br/>location ui<br/>[Map.tsx]"]
end

subgraph group_backend["Backend"]
  node_back_server["API Server<br/>node entrypoint<br/>[index.ts]"]
  node_back_routes["Route Modules<br/>rest api"]
  node_back_mw["Middleware<br/>access control"]
  node_back_socket["Realtime Socket<br/>websocket layer<br/>[socket.ts]"]
  node_back_db[("Database Layer<br/>persistence<br/>[db.ts]")]
  node_back_storage[("Storage<br/>[storage.ts]")]
  node_back_email["Email Utils<br/>transactional email<br/>[email.ts]"]
  node_back_admin_boot["Admin Bootstrap<br/>ops script<br/>[make-admin.ts]"]
  node_back_init["DB Init<br/>bootstrap<br/>[init-db.ts]"]
end

subgraph group_ops["Ops"]
  node_ops_compose["Compose Setup<br/>deployment<br/>[docker-compose.yml]"]
end

node_front_app -->|"routes"| node_front_auth
node_front_app -->|"routes"| node_front_home
node_front_app -->|"routes"| node_front_trip
node_front_app -->|"routes"| node_front_profile
node_front_app -->|"routes"| node_front_admin
node_front_app -->|"uses"| node_front_ui
node_front_app -->|"wraps"| node_front_session
node_front_home -->|"fetches"| node_front_api
node_front_trip -->|"fetches"| node_front_api
node_front_profile -->|"fetches"| node_front_api
node_front_admin -->|"fetches"| node_front_api
node_front_ui -->|"includes"| node_front_map
node_front_ui -->|"uses"| node_front_session
node_back_server -->|"mounts"| node_back_routes
node_back_server -->|"guards"| node_back_mw
node_back_server -->|"starts"| node_back_socket
node_back_server -->|"uses"| node_back_db
node_back_routes -->|"reads/writes"| node_back_db
node_back_routes -->|"sends"| node_back_email
node_back_routes -->|"uses"| node_back_storage
node_back_socket -->|"reads/writes"| node_back_db
node_back_init -->|"initializes"| node_back_db
node_back_admin_boot -->|"seeds"| node_back_db
node_ops_compose -->|"deploys"| node_front_app
node_ops_compose -->|"deploys"| node_back_server
node_front_api -->|"calls"| node_back_server
node_front_session -->|"auth flow"| node_back_routes
node_front_ui -->|"realtime"| node_back_socket

click node_front_app "https://github.com/rawepatj/tidrod/tree/main/front/app"
click node_front_auth "https://github.com/rawepatj/tidrod/tree/main/front/app/login"
click node_front_home "https://github.com/rawepatj/tidrod/tree/main/front/app/home"
click node_front_trip "https://github.com/rawepatj/tidrod/tree/main/front/app/trip/[id]"
click node_front_profile "https://github.com/rawepatj/tidrod/tree/main/front/app/profile"
click node_front_admin "https://github.com/rawepatj/tidrod/tree/main/front/app/admin"
click node_front_ui "https://github.com/rawepatj/tidrod/tree/main/front/components"
click node_front_api "https://github.com/rawepatj/tidrod/blob/main/front/lib/api.ts"
click node_front_session "https://github.com/rawepatj/tidrod/blob/main/front/components/SessionProvider.tsx"
click node_front_map "https://github.com/rawepatj/tidrod/blob/main/front/components/Map.tsx"
click node_back_server "https://github.com/rawepatj/tidrod/blob/main/back/src/index.ts"
click node_back_routes "https://github.com/rawepatj/tidrod/tree/main/back/src/routes"
click node_back_mw "https://github.com/rawepatj/tidrod/tree/main/back/src/middleware"
click node_back_socket "https://github.com/rawepatj/tidrod/blob/main/back/src/socket.ts"
click node_back_db "https://github.com/rawepatj/tidrod/blob/main/back/src/db.ts"
click node_back_storage "https://github.com/rawepatj/tidrod/blob/main/back/src/storage.ts"
click node_back_email "https://github.com/rawepatj/tidrod/blob/main/back/src/utils/email.ts"
click node_back_admin_boot "https://github.com/rawepatj/tidrod/blob/main/back/src/scripts/make-admin.ts"
click node_back_init "https://github.com/rawepatj/tidrod/blob/main/back/src/init-db.ts"
click node_ops_compose "https://github.com/rawepatj/tidrod/blob/main/docker-compose.yml"

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_front_app,node_front_auth,node_front_home,node_front_trip,node_front_profile,node_front_admin,node_front_ui,node_front_api,node_front_session,node_front_map toneBlue
class node_back_server,node_back_routes,node_back_mw,node_back_socket,node_back_db,node_back_storage,node_back_email,node_back_admin_boot,node_back_init toneAmber
class node_ops_compose toneMint
```

## Components

### Frontend

Next.js App Router UI and client-side feature flows

- [App Router](https://github.com/rawepatj/tidrod/tree/main/front/app): nextjs routes · Top-level Next.js application shell and route segments · `front/app`
- [Auth Pages](https://github.com/rawepatj/tidrod/tree/main/front/app/login): user flows · Login, register, password reset, and email verification screens · `front/app/login`
- [Home Feed](https://github.com/rawepatj/tidrod/tree/main/front/app/home): trip discovery · Primary landing and trip browsing experience · `front/app/home`
- [Trip Detail](https://github.com/rawepatj/tidrod/tree/main/front/app/trip/[id]): trip page · Trip view and participation flow for a specific trip · `front/app/trip/[id]`
- [Profile](https://github.com/rawepatj/tidrod/tree/main/front/app/profile): account page · User profile and account settings surface · `front/app/profile`
- [Admin Console](https://github.com/rawepatj/tidrod/tree/main/front/app/admin): ops UI · Separate administrative area for moderation and oversight · `front/app/admin`
- [UI Components](https://github.com/rawepatj/tidrod/tree/main/front/components): shared components · Reusable client-side components for trips, chat, map, notifications, and forms · `front/components`
- [API Client](https://github.com/rawepatj/tidrod/blob/main/front/lib/api.ts): browser client · Frontend integration layer for backend requests · `front/lib/api.ts`
- [Session State](https://github.com/rawepatj/tidrod/blob/main/front/components/SessionProvider.tsx): client state · Auth/session provider and UI feedback primitives · `front/components/SessionProvider.tsx`
- [Map UI](https://github.com/rawepatj/tidrod/blob/main/front/components/Map.tsx): location ui · Map rendering and location autocomplete support · `front/components/Map.tsx`

### Backend

TypeScript Node API, realtime, and persistence boundary

- [API Server](https://github.com/rawepatj/tidrod/blob/main/back/src/index.ts): node entrypoint · Backend application entrypoint and HTTP server bootstrap · `back/src/index.ts`
- [Route Modules](https://github.com/rawepatj/tidrod/tree/main/back/src/routes): rest api · Domain API routes for auth, users, trips, messages, notifications, reports, markers, and admin · `back/src/routes`
- [Middleware](https://github.com/rawepatj/tidrod/tree/main/back/src/middleware): access control · Authentication and admin authorization guards · `back/src/middleware`
- [Realtime Socket](https://github.com/rawepatj/tidrod/blob/main/back/src/socket.ts): websocket layer · Websocket-based chat and live notification channel · `back/src/socket.ts`
- [Database Layer](https://github.com/rawepatj/tidrod/blob/main/back/src/db.ts): persistence · Database access and schema/runtime initialization · `back/src/db.ts`
- [Storage](https://github.com/rawepatj/tidrod/blob/main/back/src/storage.ts): file/blob storage · Backend storage abstraction for persisted assets or files · `back/src/storage.ts`
- [Email Utils](https://github.com/rawepatj/tidrod/blob/main/back/src/utils/email.ts): transactional email · Account lifecycle email delivery for verification and recovery · `back/src/utils/email.ts`
- [Admin Bootstrap](https://github.com/rawepatj/tidrod/blob/main/back/src/scripts/make-admin.ts): ops script · Script for creating an administrative user or seed admin access · `back/src/scripts/make-admin.ts`
- [DB Init](https://github.com/rawepatj/tidrod/blob/main/back/src/init-db.ts): bootstrap · Startup/bootstrap flow for database setup and initialization · `back/src/init-db.ts`

### Ops

Container and bootstrap support for local/containerized deployment

- [Compose Setup](https://github.com/rawepatj/tidrod/blob/main/docker-compose.yml): deployment · Container orchestration for frontend and backend services · `docker-compose.yml`

## Connections

- App Router → Auth Pages: routes · App Router exposes authentication pages
- App Router → Home Feed: routes · App Router exposes the home feed
- App Router → Trip Detail: routes · App Router exposes trip detail pages
- App Router → Profile: routes · App Router exposes profile pages
- App Router → Admin Console: routes · App Router exposes the admin surface
- App Router → UI Components: uses · Route pages compose shared client components
- App Router → Session State: wraps · App shell provides session and toast/state infrastructure
- Home Feed → API Client: fetches · Home and discovery views load data from the API client
- Trip Detail → API Client: fetches · Trip detail and participation flows call backend endpoints
- Profile → API Client: fetches · Profile views read and update user data through the API client
- Admin Console → API Client: fetches · Admin pages consume admin endpoints through the API client
- UI Components → Map UI: includes · Shared UI includes map, autocomplete, and trip creation widgets
- UI Components → Session State: uses · Components depend on session/auth and feedback primitives
- API Server → Route Modules: mounts · Server mounts domain route modules
- API Server → Middleware: guards · Server applies auth and admin middleware
- API Server → Realtime Socket: starts · Server initializes realtime connections
- API Server → Database Layer: uses · Server depends on persistence layer
- Route Modules → Database Layer: reads/writes · Domain routes persist and query application data
- Route Modules → Email Utils: sends · Auth routes trigger transactional email flows
- Route Modules → Storage: uses · Some routes rely on backend storage abstractions
- Realtime Socket → Database Layer: reads/writes · Realtime features share persisted state with the database
- DB Init → Database Layer: initializes · Startup/bootstrap prepares the database
- Admin Bootstrap → Database Layer: seeds · Admin bootstrap creates or promotes admin access in persistence
- Compose Setup → App Router: deploys · Compose orchestrates the frontend service
- Compose Setup → API Server: deploys · Compose orchestrates the backend service
- API Client → API Server: calls · Browser UI talks to the backend API
- Session State → Route Modules: auth flow · Session state depends on backend auth and user endpoints
- UI Components → Realtime Socket: realtime · Chat and notification UI consume websocket events
