# davidericson00/cade architecture

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

- Interactive diagram: https://gitdiagram.com/davidericson00/cade
- Repository: https://github.com/davidericson00/cade

## Overview

Cadê? is a lost-and-found web platform: visitors browse and filter items and download reports, while administrators register, authenticate with emailed two-factor codes, manage items, and inspect access logs. The SPA routes these tasks through a shared HTTP client to the Express API; API handlers delegate domain work to services and repositories, with MongoDB and optional Cloudinary/SMTP integrations. README descriptions supply important unsampled capabilities; edges are limited to relationships evidenced by excerpts, indexed references, or README statements.

Main entry points: [`web/src/api/client.ts`](https://github.com/davidericson00/cade/blob/main/web/src/api/client.ts) (HTTP client), [`web/src/routes.tsx`](https://github.com/davidericson00/cade/blob/main/web/src/routes.tsx) (Page routing), [`api/src/routes/items.routes.ts`](https://github.com/davidericson00/cade/blob/main/api/src/routes/items.routes.ts) (Item endpoints), [`web/src/pages/logs/LogsPage.tsx`](https://github.com/davidericson00/cade/blob/main/web/src/pages/logs/LogsPage.tsx) (Access log viewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_routes["Page routing<br/>[routes.tsx]"]
  node_item_views["Item browsing"]
  node_item_form["Item editor<br/>[ItemFormPage.tsx]"]
  node_report_view["Report downloads<br/>[ReportsPage.tsx]"]
  node_log_view["Access log viewer<br/>[LogsPage.tsx]"]
  node_web_client["HTTP client<br/>[client.ts]"]
  node_system["System status gate"]
end

subgraph group_identity["Identity and access"]
  node_auth_views["Login and 2FA"]
  node_session["Session state<br/>[session.ts]"]
  node_auth_controller["Authentication handlers<br/>[auth.controller.ts]"]
  node_auth_service["Account authentication<br/>[auth.service.ts]"]
  node_twofactor["Challenge service"]
  node_mail["Email delivery<br/>[email.service.ts]"]
end

subgraph group_items["Item management"]
  node_item_routes["Item endpoints<br/>[items.routes.ts]"]
  node_item_controller["Item handlers"]
  node_item_service["Item operations<br/>[items.service.ts]"]
  node_item_repository["Item persistence"]
  node_image_storage["Image storage<br/>[storage.service.ts]"]
end

subgraph group_operations["Reports and operations"]
  node_report_controller["PDF report handler"]
  node_export_controller["CSV export handler"]
  node_report_service["PDF generation<br/>[report.service.ts]"]
  node_export_service["CSV generation<br/>[export.service.ts]"]
  node_log_view_controller["Log handlers"]
  node_log_service["Log queries"]
  node_log_data[("In-memory request logs<br/>[request-logs.ts]")]
end

subgraph group_api["API foundation"]
  node_express["Express application<br/>[app.ts]"]
  node_mongo[("MongoDB")]
end

node_visitor(("Visitor or admin"))
node_cloudinary[("Cloudinary")]
node_smtp["SMTP service"]
node_browser(("Browser"))

node_visitor -->|"uses"| node_routes
node_routes -->|"routes to"| node_item_views
node_routes -->|"routes to"| node_item_form
node_routes -->|"routes to"| node_report_view
node_routes -->|"routes to"| node_log_view
node_routes -->|"routes to"| node_auth_views
node_item_form -->|"calls"| node_web_client
node_report_view -->|"downloads via"| node_web_client
node_log_view -->|"fetches via"| node_web_client
node_auth_views -->|"calls"| node_web_client
node_web_client -->|"reads token"| node_session
node_web_client -->|"HTTP requests"| node_express
node_browser -->|"runs"| node_web_client
node_web_client -->|"signals failures"| node_system
node_express -->|"mounts routes"| node_item_routes
node_item_routes -->|"dispatches"| node_item_controller
node_item_controller -->|"calls"| node_item_service
node_item_service -->|"uses"| node_item_repository
node_item_repository -->|"persists items"| node_mongo
node_item_controller -->|"calls"| node_image_storage
node_image_storage -->|"uploads or deletes"| node_cloudinary
node_auth_controller -->|"starts login"| node_auth_service
node_auth_controller -->|"verifies or resends"| node_twofactor
node_auth_service -->|"starts challenge"| node_twofactor
node_twofactor -->|"sends codes"| node_mail
node_mail -->|"delivers email"| node_smtp
node_item_routes -->|"dispatches report"| node_report_controller
node_item_routes -->|"dispatches export"| node_export_controller
node_report_controller -->|"calls"| node_report_service
node_export_controller -->|"calls"| node_export_service
node_log_view -->|"requests logs"| node_log_view_controller
node_log_view_controller -.->|"delegates"| node_log_service
node_log_service -.->|"reads logs"| node_log_data

click node_routes "https://github.com/davidericson00/cade/blob/main/web/src/routes.tsx"
click node_item_views "https://github.com/davidericson00/cade/tree/main/web/src/pages/items"
click node_item_form "https://github.com/davidericson00/cade/blob/main/web/src/pages/items/ItemFormPage.tsx"
click node_report_view "https://github.com/davidericson00/cade/blob/main/web/src/pages/reports/ReportsPage.tsx"
click node_log_view "https://github.com/davidericson00/cade/blob/main/web/src/pages/logs/LogsPage.tsx"
click node_auth_views "https://github.com/davidericson00/cade/tree/main/web/src/pages/auth"
click node_web_client "https://github.com/davidericson00/cade/blob/main/web/src/api/client.ts"
click node_session "https://github.com/davidericson00/cade/blob/main/web/src/auth/session.ts"
click node_system "https://github.com/davidericson00/cade/tree/main/web/src/system"
click node_express "https://github.com/davidericson00/cade/blob/main/api/src/app.ts"
click node_item_routes "https://github.com/davidericson00/cade/blob/main/api/src/routes/items.routes.ts"
click node_item_controller "https://github.com/davidericson00/cade/blob/main/api/src/controllers/items.controller.ts"
click node_item_service "https://github.com/davidericson00/cade/blob/main/api/src/services/items.service.ts"
click node_item_repository "https://github.com/davidericson00/cade/blob/main/api/src/repositories/items.repository.ts"
click node_image_storage "https://github.com/davidericson00/cade/blob/main/api/src/services/storage.service.ts"
click node_auth_controller "https://github.com/davidericson00/cade/blob/main/api/src/controllers/auth.controller.ts"
click node_auth_service "https://github.com/davidericson00/cade/blob/main/api/src/services/auth.service.ts"
click node_twofactor "https://github.com/davidericson00/cade/blob/main/api/src/services/twoFactor.service.ts"
click node_mail "https://github.com/davidericson00/cade/blob/main/api/src/services/email.service.ts"
click node_report_controller "https://github.com/davidericson00/cade/blob/main/api/src/controllers/report.controller.ts"
click node_export_controller "https://github.com/davidericson00/cade/blob/main/api/src/controllers/export.controller.ts"
click node_report_service "https://github.com/davidericson00/cade/blob/main/api/src/services/report.service.ts"
click node_export_service "https://github.com/davidericson00/cade/blob/main/api/src/services/export.service.ts"
click node_log_view_controller "https://github.com/davidericson00/cade/blob/main/api/src/controllers/requestLog.controller.ts"
click node_log_service "https://github.com/davidericson00/cade/blob/main/api/src/services/requestLog.service.ts"
click node_log_data "https://github.com/davidericson00/cade/blob/main/api/src/data/request-logs.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_routes,node_item_views,node_item_form,node_report_view,node_log_view,node_web_client,node_system,node_browser toneBlue
class node_auth_views,node_session,node_auth_controller,node_auth_service,node_twofactor,node_mail,node_cloudinary toneAmber
class node_item_routes,node_item_controller,node_item_service,node_item_repository,node_image_storage toneMint
class node_report_controller,node_export_controller,node_report_service,node_export_service,node_log_view_controller,node_log_service,node_log_data toneRose
class node_express,node_mongo,node_visitor,node_smtp toneIndigo
```

## Components

### Web experience

- [Page routing](https://github.com/davidericson00/cade/blob/main/web/src/routes.tsx): `web/src/routes.tsx`
- [Item browsing](https://github.com/davidericson00/cade/tree/main/web/src/pages/items): `web/src/pages/items`
- [Item editor](https://github.com/davidericson00/cade/blob/main/web/src/pages/items/ItemFormPage.tsx): `web/src/pages/items/ItemFormPage.tsx`
- [Report downloads](https://github.com/davidericson00/cade/blob/main/web/src/pages/reports/ReportsPage.tsx): `web/src/pages/reports/ReportsPage.tsx`
- [Access log viewer](https://github.com/davidericson00/cade/blob/main/web/src/pages/logs/LogsPage.tsx): `web/src/pages/logs/LogsPage.tsx`
- [HTTP client](https://github.com/davidericson00/cade/blob/main/web/src/api/client.ts): `web/src/api/client.ts`
- [System status gate](https://github.com/davidericson00/cade/tree/main/web/src/system): `web/src/system`

### Identity and access

- [Login and 2FA](https://github.com/davidericson00/cade/tree/main/web/src/pages/auth): `web/src/pages/auth`
- [Session state](https://github.com/davidericson00/cade/blob/main/web/src/auth/session.ts): `web/src/auth/session.ts`
- [Authentication handlers](https://github.com/davidericson00/cade/blob/main/api/src/controllers/auth.controller.ts): `api/src/controllers/auth.controller.ts`
- [Account authentication](https://github.com/davidericson00/cade/blob/main/api/src/services/auth.service.ts): `api/src/services/auth.service.ts`
- [Challenge service](https://github.com/davidericson00/cade/blob/main/api/src/services/twoFactor.service.ts): `api/src/services/twoFactor.service.ts`
- [Email delivery](https://github.com/davidericson00/cade/blob/main/api/src/services/email.service.ts): `api/src/services/email.service.ts`

### Item management

- [Item endpoints](https://github.com/davidericson00/cade/blob/main/api/src/routes/items.routes.ts): `api/src/routes/items.routes.ts`
- [Item handlers](https://github.com/davidericson00/cade/blob/main/api/src/controllers/items.controller.ts): `api/src/controllers/items.controller.ts`
- [Item operations](https://github.com/davidericson00/cade/blob/main/api/src/services/items.service.ts): `api/src/services/items.service.ts`
- [Item persistence](https://github.com/davidericson00/cade/blob/main/api/src/repositories/items.repository.ts): `api/src/repositories/items.repository.ts`
- [Image storage](https://github.com/davidericson00/cade/blob/main/api/src/services/storage.service.ts): `api/src/services/storage.service.ts`

### Reports and operations

- [PDF report handler](https://github.com/davidericson00/cade/blob/main/api/src/controllers/report.controller.ts): `api/src/controllers/report.controller.ts`
- [CSV export handler](https://github.com/davidericson00/cade/blob/main/api/src/controllers/export.controller.ts): `api/src/controllers/export.controller.ts`
- [PDF generation](https://github.com/davidericson00/cade/blob/main/api/src/services/report.service.ts): `api/src/services/report.service.ts`
- [CSV generation](https://github.com/davidericson00/cade/blob/main/api/src/services/export.service.ts): `api/src/services/export.service.ts`
- [Log handlers](https://github.com/davidericson00/cade/blob/main/api/src/controllers/requestLog.controller.ts): `api/src/controllers/requestLog.controller.ts`
- [Log queries](https://github.com/davidericson00/cade/blob/main/api/src/services/requestLog.service.ts): `api/src/services/requestLog.service.ts`
- [In-memory request logs](https://github.com/davidericson00/cade/blob/main/api/src/data/request-logs.ts): `api/src/data/request-logs.ts`

### API foundation

- [Express application](https://github.com/davidericson00/cade/blob/main/api/src/app.ts): `api/src/app.ts`
- **MongoDB**

### Other components

- **Visitor or admin**
- **Cloudinary**
- **SMTP service**
- **Browser**

## Connections

- Visitor or admin → Page routing: uses
- Page routing → Item browsing: routes to (evidence: `web/src/routes.tsx`)
- Page routing → Item editor: routes to (evidence: `web/src/routes.tsx`)
- Page routing → Report downloads: routes to (evidence: `web/src/routes.tsx`)
- Page routing → Access log viewer: routes to (evidence: `web/src/routes.tsx`)
- Page routing → Login and 2FA: routes to (evidence: `web/src/routes.tsx`)
- Item editor → HTTP client: calls (evidence: `web/src/pages/items/ItemFormPage.tsx`)
- Report downloads → HTTP client: downloads via
- Access log viewer → HTTP client: fetches via (evidence: `web/src/pages/logs/LogsPage.tsx`)
- Login and 2FA → HTTP client: calls (evidence: `web/src/pages/auth/TwoFactorPage.tsx`)
- HTTP client → Session state: reads token (evidence: `web/src/api/client.ts`)
- HTTP client → Express application: HTTP requests
- Browser → HTTP client: runs
- HTTP client → System status gate: signals failures (evidence: `web/src/App.tsx`)
- Express application → Item endpoints: mounts routes (evidence: `api/src/app.ts`)
- Item endpoints → Item handlers: dispatches (evidence: `api/src/routes/items.routes.ts`)
- Item handlers → Item operations: calls (evidence: `api/src/controllers/items.controller.ts`)
- Item operations → Item persistence: uses (evidence: `api/src/services/items.service.ts`)
- Item persistence → MongoDB: persists items (evidence: `api/src/repositories/items.repository.ts`)
- Item handlers → Image storage: calls (evidence: `api/src/controllers/items.controller.ts`)
- Image storage → Cloudinary: uploads or deletes (evidence: `api/src/services/storage.service.ts`)
- Authentication handlers → Account authentication: starts login (evidence: `api/src/controllers/auth.controller.ts`)
- Authentication handlers → Challenge service: verifies or resends (evidence: `api/src/controllers/auth.controller.ts`)
- Account authentication → Challenge service: starts challenge (evidence: `api/src/services/auth.service.ts`)
- Challenge service → Email delivery: sends codes (evidence: `api/src/services/twoFactor.service.ts`)
- Email delivery → SMTP service: delivers email
- Item endpoints → PDF report handler: dispatches report (evidence: `api/src/routes/items.routes.ts`)
- Item endpoints → CSV export handler: dispatches export (evidence: `api/src/routes/items.routes.ts`)
- PDF report handler → PDF generation: calls (evidence: `api/src/controllers/report.controller.ts`)
- CSV export handler → CSV generation: calls (evidence: `api/src/controllers/export.controller.ts`)
- Access log viewer → Log handlers: requests logs
- Log handlers → Log queries: delegates
- Log queries → In-memory request logs: reads logs
