# antorghsd/lostfound-uni architecture

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

- Interactive diagram: https://gitdiagram.com/antorghsd/lostfound-uni
- Repository: https://github.com/antorghsd/lostfound-uni

## Overview

The University Lost & Found Platform lets students and staff report and find items, pursue claims and handovers, and receive match notifications; administrators moderate users, items, categories, reports, and locations. The main flow runs from web or admin clients through the API to application use cases and persisted data, with matching and email workers supporting recovery. The README documents real-time behavior, but the socket implementation was not sampled, so its runtime links are shown as unverified. Frontend-to-API calls and several unsampled feature internals are likewise not asserted.

Main entry points: [`apps/api/src/server.ts`](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/server.ts) (HTTP API Server), [`apps/api/src/infrastructure/database/prisma.ts`](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/infrastructure/database/prisma.ts) (Application Database), [`apps/api/src/interface/http/routes/index.ts`](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/routes/index.ts) (API Route Registry), [`apps/web/src/App.tsx`](https://github.com/antorghsd/lostfound-uni/blob/main/apps/web/src/App.tsx) (Web App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Applications"]
  node_webapp["Web App<br/>[App.tsx]"]
  node_webfeatures["Item &amp; Claim Pages"]
  node_adminapp["Admin Panel<br/>[App.tsx]"]
  node_adminfeatures["Admin Operations"]
end

subgraph group_http["API Interface"]
  node_api["HTTP API Server<br/>[server.ts]"]
  node_routes["API Route Registry<br/>[index.ts]"]
  node_authroutes["Auth Routes<br/>[auth.routes.ts]"]
  node_authcontroller["Auth Controller<br/>[auth.controller.ts]"]
  node_adminroutes["Admin Routes<br/>[admin.routes.ts]"]
  node_itemroutes["Item Routes<br/>[item.routes.ts]"]
  node_claimroutes["Claim Routes<br/>[claim.routes.ts]"]
end

subgraph group_domain["Recovery Workflows"]
  node_authservice["Authentication<br/>[auth.service.ts]"]
  node_itemservice["Item Management<br/>[item.service.ts]"]
  node_claimservice["Claims &amp; Handovers<br/>[claim.service.ts]"]
  node_matchservice["Match Scoring<br/>[match.service.ts]"]
end

subgraph group_infra["Platform Services"]
  node_matchingqueue["Matching Worker<br/>[matching.queue.ts]"]
  node_emailqueue["Email Worker<br/>[email.queue.ts]"]
  node_emailservice["Email Delivery<br/>[email.service.ts]"]
  node_socket["Realtime Socket<br/>[index.ts]"]
  node_cloudstorage["Image Storage"]
  node_database[("Application Database<br/>[prisma.ts]")]
  node_types["Shared Types<br/>[index.ts]"]
  node_validators["Shared Validators<br/>[index.ts]"]
end

node_students(("Students &amp; Staff"))

node_api -->|"mounts routes"| node_routes
node_api -->|"starts worker"| node_matchingqueue
node_api -->|"starts worker"| node_emailqueue
node_api -->|"verifies SMTP"| node_emailservice
node_api -->|"initializes socket"| node_socket
node_routes -->|"registers"| node_authroutes
node_routes -->|"registers"| node_itemroutes
node_routes -->|"registers"| node_claimroutes
node_routes -->|"registers"| node_adminroutes
node_authroutes -->|"routes requests"| node_authcontroller
node_authcontroller -->|"calls"| node_authservice
node_authcontroller -->|"reads profile"| node_database
node_authservice -->|"reads and writes"| node_database
node_adminroutes -->|"reads and writes"| node_database
node_itemservice -->|"reads and writes"| node_database
node_claimservice -->|"reads and writes"| node_database
node_matchingqueue -->|"dispatches work"| node_matchservice
node_emailqueue -->|"sends email"| node_emailservice
node_emailqueue -->|"reads queued data"| node_database
node_students -.->|"uses"| node_webapp
node_webapp -.->|"calls API"| node_api
node_adminapp -.->|"calls API"| node_api
node_webapp -.->|"presents"| node_webfeatures
node_adminapp -.->|"presents"| node_adminfeatures
node_webapp -.->|"realtime updates"| node_socket
node_webfeatures -.->|"uploads images"| node_cloudstorage

click node_webapp "https://github.com/antorghsd/lostfound-uni/blob/main/apps/web/src/App.tsx"
click node_webfeatures "https://github.com/antorghsd/lostfound-uni/tree/main/apps/web/src/features"
click node_adminapp "https://github.com/antorghsd/lostfound-uni/blob/main/apps/admin/src/App.tsx"
click node_adminfeatures "https://github.com/antorghsd/lostfound-uni/tree/main/apps/admin/src/features"
click node_api "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/server.ts"
click node_routes "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/routes/index.ts"
click node_authroutes "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/routes/auth.routes.ts"
click node_authcontroller "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/controllers/auth.controller.ts"
click node_adminroutes "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/routes/admin.routes.ts"
click node_itemroutes "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/routes/item.routes.ts"
click node_claimroutes "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/routes/claim.routes.ts"
click node_authservice "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/application/use-cases/auth.service.ts"
click node_itemservice "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/application/use-cases/item.service.ts"
click node_claimservice "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/application/use-cases/claim.service.ts"
click node_matchservice "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/application/use-cases/match.service.ts"
click node_matchingqueue "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/infrastructure/queue/matching.queue.ts"
click node_emailqueue "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/infrastructure/queue/email.queue.ts"
click node_emailservice "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/infrastructure/email/email.service.ts"
click node_socket "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/socket/index.ts"
click node_cloudstorage "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/infrastructure/storage/cloudinary.service.ts"
click node_database "https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/infrastructure/database/prisma.ts"
click node_types "https://github.com/antorghsd/lostfound-uni/blob/main/packages/types/src/index.ts"
click node_validators "https://github.com/antorghsd/lostfound-uni/blob/main/packages/validators/src/index.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_webapp,node_webfeatures,node_adminapp,node_adminfeatures toneBlue
class node_api,node_routes,node_authroutes,node_authcontroller,node_adminroutes,node_itemroutes,node_claimroutes toneAmber
class node_authservice,node_itemservice,node_claimservice,node_matchservice toneMint
class node_matchingqueue,node_emailqueue,node_emailservice,node_socket,node_cloudstorage,node_database,node_types,node_validators toneRose
class node_students toneIndigo
```

## Components

### User Applications

- [Web App](https://github.com/antorghsd/lostfound-uni/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Item & Claim Pages](https://github.com/antorghsd/lostfound-uni/tree/main/apps/web/src/features): `apps/web/src/features`
- [Admin Panel](https://github.com/antorghsd/lostfound-uni/blob/main/apps/admin/src/App.tsx): `apps/admin/src/App.tsx`
- [Admin Operations](https://github.com/antorghsd/lostfound-uni/tree/main/apps/admin/src/features): `apps/admin/src/features`

### API Interface

- [HTTP API Server](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/server.ts): `apps/api/src/server.ts`
- [API Route Registry](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/routes/index.ts): `apps/api/src/interface/http/routes/index.ts`
- [Auth Routes](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/routes/auth.routes.ts): `apps/api/src/interface/http/routes/auth.routes.ts`
- [Auth Controller](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/controllers/auth.controller.ts): `apps/api/src/interface/http/controllers/auth.controller.ts`
- [Admin Routes](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/routes/admin.routes.ts): `apps/api/src/interface/http/routes/admin.routes.ts`
- [Item Routes](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/routes/item.routes.ts): `apps/api/src/interface/http/routes/item.routes.ts`
- [Claim Routes](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/http/routes/claim.routes.ts): `apps/api/src/interface/http/routes/claim.routes.ts`

### Recovery Workflows

- [Authentication](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/application/use-cases/auth.service.ts): `apps/api/src/application/use-cases/auth.service.ts`
- [Item Management](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/application/use-cases/item.service.ts): `apps/api/src/application/use-cases/item.service.ts`
- [Claims & Handovers](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/application/use-cases/claim.service.ts): `apps/api/src/application/use-cases/claim.service.ts`
- [Match Scoring](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/application/use-cases/match.service.ts): `apps/api/src/application/use-cases/match.service.ts`

### Platform Services

- [Matching Worker](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/infrastructure/queue/matching.queue.ts): `apps/api/src/infrastructure/queue/matching.queue.ts`
- [Email Worker](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/infrastructure/queue/email.queue.ts): `apps/api/src/infrastructure/queue/email.queue.ts`
- [Email Delivery](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/infrastructure/email/email.service.ts): `apps/api/src/infrastructure/email/email.service.ts`
- [Realtime Socket](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/interface/socket/index.ts): `apps/api/src/interface/socket/index.ts`
- [Image Storage](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/infrastructure/storage/cloudinary.service.ts): `apps/api/src/infrastructure/storage/cloudinary.service.ts`
- [Application Database](https://github.com/antorghsd/lostfound-uni/blob/main/apps/api/src/infrastructure/database/prisma.ts): `apps/api/src/infrastructure/database/prisma.ts`
- [Shared Types](https://github.com/antorghsd/lostfound-uni/blob/main/packages/types/src/index.ts): `packages/types/src/index.ts`
- [Shared Validators](https://github.com/antorghsd/lostfound-uni/blob/main/packages/validators/src/index.ts): `packages/validators/src/index.ts`

### Other components

- **Students & Staff**

## Connections

- HTTP API Server → API Route Registry: mounts routes (evidence: `apps/api/src/server.ts`)
- HTTP API Server → Matching Worker: starts worker (evidence: `apps/api/src/server.ts`)
- HTTP API Server → Email Worker: starts worker (evidence: `apps/api/src/server.ts`)
- HTTP API Server → Email Delivery: verifies SMTP (evidence: `apps/api/src/server.ts`)
- HTTP API Server → Realtime Socket: initializes socket (evidence: `apps/api/src/server.ts`)
- API Route Registry → Auth Routes: registers (evidence: `apps/api/src/interface/http/routes/index.ts`)
- API Route Registry → Item Routes: registers (evidence: `apps/api/src/interface/http/routes/index.ts`)
- API Route Registry → Claim Routes: registers (evidence: `apps/api/src/interface/http/routes/index.ts`)
- API Route Registry → Admin Routes: registers (evidence: `apps/api/src/interface/http/routes/index.ts`)
- Auth Routes → Auth Controller: routes requests (evidence: `apps/api/src/interface/http/routes/auth.routes.ts`)
- Auth Controller → Authentication: calls (evidence: `apps/api/src/interface/http/controllers/auth.controller.ts`)
- Auth Controller → Application Database: reads profile (evidence: `apps/api/src/interface/http/controllers/auth.controller.ts`)
- Authentication → Application Database: reads and writes (evidence: `apps/api/src/application/use-cases/auth.service.ts`)
- Admin Routes → Application Database: reads and writes (evidence: `apps/api/src/interface/http/routes/admin.routes.ts`)
- Item Management → Application Database: reads and writes (evidence: `apps/api/src/application/use-cases/item.service.ts`)
- Claims & Handovers → Application Database: reads and writes (evidence: `apps/api/src/application/use-cases/claim.service.ts`)
- Matching Worker → Match Scoring: dispatches work (evidence: `apps/api/src/infrastructure/queue/matching.queue.ts`)
- Email Worker → Email Delivery: sends email (evidence: `apps/api/src/infrastructure/queue/email.queue.ts`)
- Email Worker → Application Database: reads queued data (evidence: `apps/api/src/infrastructure/queue/email.queue.ts`)
- Students & Staff → Web App: uses
- Web App → HTTP API Server: calls API
- Admin Panel → HTTP API Server: calls API
- Web App → Item & Claim Pages: presents
- Admin Panel → Admin Operations: presents
- Web App → Realtime Socket: realtime updates
- Item & Claim Pages → Image Storage: uploads images
