# maharikha/campus-lost-found architecture

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

- Interactive diagram: https://gitdiagram.com/maharikha/campus-lost-found
- Repository: https://github.com/maharikha/campus-lost-found

## Overview

Campus Lost & Found lets students report lost or found items, find explained matches, answer a targeted disambiguation question, and prove ownership before pickup; desk staff record handovers. The frontend routes users through reporting, match review, claims, and the desk, while a FastAPI backend enriches reports, ranks candidates, verifies claims, and persists state. The README documents alerts and email plus rule-based fallbacks for optional AI. Backend wiring is only partly excerpted, so links based on the source index are limited to named dependencies; unsampled feature details are not inferred.

Main entry points: [`frontend/src/App.jsx`](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/App.jsx) (App routing), [`backend/app.py`](https://github.com/maharikha/campus-lost-found/blob/main/backend/app.py) (HTTP workflows), [`frontend/src/api.js`](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/api.js) (API client), [`frontend/src/pages/Home.jsx`](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/pages/Home.jsx) (Browse items)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["App routing<br/>[App.jsx]"]
  node_home["Browse items<br/>[Home.jsx]"]
  node_reportform["Report item<br/>[ReportForm.jsx]"]
  node_reportpage["Match results<br/>[ReportPage.jsx]"]
  node_claimpage["Claim verification<br/>[ClaimPage.jsx]"]
  node_deskpage["Staff desk<br/>[Desk.jsx]"]
  node_api["API client<br/>[api.js]"]
  node_tagcard["Item cards<br/>[TagCard.jsx]"]
  node_format["Display formatting<br/>[format.js]"]
  node_browserstore[("Report reminders<br/>[store.js]")]
end

subgraph group_workflow["Report and claim"]
  node_backend["HTTP workflows<br/>[app.py]"]
  node_verify["Ownership proof<br/>[verify.py]"]
end

subgraph group_matching["Matching services"]
  node_enrich["Report enrichment<br/>[enrich.py]"]
  node_matcher["Candidate ranking<br/>[matcher.py]"]
  node_llm["Optional language model<br/>[llm.py]"]
end

subgraph group_state["Persistence and alerts"]
  node_db[("SQLite records<br/>[db.py]")]
  node_notify["Owner alerts<br/>[notify.py]"]
end

node_student(("Student or finder"))
node_staff(("Desk staff"))
node_email["Brevo SMTP"]

node_student -->|"uses"| node_app
node_staff -->|"uses"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_reportform
node_app -->|"routes to"| node_reportpage
node_app -->|"routes to"| node_claimpage
node_app -->|"routes to"| node_deskpage
node_home -->|"requests data"| node_api
node_reportform -->|"submits report"| node_api
node_reportform -->|"remembers report"| node_browserstore
node_reportpage -->|"loads matches"| node_api
node_claimpage -->|"verifies claim"| node_api
node_deskpage -->|"requests desk data"| node_api
node_home -->|"renders items"| node_tagcard
node_reportpage -->|"renders matches"| node_tagcard
node_tagcard -->|"formats details"| node_format
node_api -->|"HTTP requests"| node_backend
node_backend -->|"enriches reports"| node_enrich
node_backend -->|"ranks candidates"| node_matcher
node_backend -->|"checks ownership"| node_verify
node_backend -->|"reads and writes"| node_db
node_backend -->|"alerts owners"| node_notify
node_enrich -->|"requests extraction"| node_llm
node_notify -.->|"sends email"| node_email
node_student -.->|"answers question"| node_backend

click node_app "https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/App.jsx"
click node_home "https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/pages/Home.jsx"
click node_reportform "https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/pages/ReportForm.jsx"
click node_reportpage "https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/pages/ReportPage.jsx"
click node_claimpage "https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/pages/ClaimPage.jsx"
click node_deskpage "https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/pages/Desk.jsx"
click node_api "https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/api.js"
click node_tagcard "https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/components/TagCard.jsx"
click node_format "https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/lib/format.js"
click node_browserstore "https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/lib/store.js"
click node_backend "https://github.com/maharikha/campus-lost-found/blob/main/backend/app.py"
click node_enrich "https://github.com/maharikha/campus-lost-found/blob/main/backend/enrich.py"
click node_matcher "https://github.com/maharikha/campus-lost-found/blob/main/backend/matcher.py"
click node_verify "https://github.com/maharikha/campus-lost-found/blob/main/backend/verify.py"
click node_llm "https://github.com/maharikha/campus-lost-found/blob/main/backend/llm.py"
click node_db "https://github.com/maharikha/campus-lost-found/blob/main/backend/db.py"
click node_notify "https://github.com/maharikha/campus-lost-found/blob/main/backend/notify.py"

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_home,node_reportform,node_reportpage,node_claimpage,node_deskpage,node_api,node_tagcard,node_format,node_browserstore toneBlue
class node_backend,node_verify toneAmber
class node_enrich,node_matcher,node_llm toneMint
class node_db,node_notify toneRose
class node_student,node_staff,node_email toneIndigo
```

## Components

### Web experience

- [App routing](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Browse items](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/pages/Home.jsx): `frontend/src/pages/Home.jsx`
- [Report item](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/pages/ReportForm.jsx): `frontend/src/pages/ReportForm.jsx`
- [Match results](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/pages/ReportPage.jsx): `frontend/src/pages/ReportPage.jsx`
- [Claim verification](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/pages/ClaimPage.jsx): `frontend/src/pages/ClaimPage.jsx`
- [Staff desk](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/pages/Desk.jsx): `frontend/src/pages/Desk.jsx`
- [API client](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Item cards](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/components/TagCard.jsx): `frontend/src/components/TagCard.jsx`
- [Display formatting](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/lib/format.js): `frontend/src/lib/format.js`
- [Report reminders](https://github.com/maharikha/campus-lost-found/blob/main/frontend/src/lib/store.js): `frontend/src/lib/store.js`

### Report and claim

- [HTTP workflows](https://github.com/maharikha/campus-lost-found/blob/main/backend/app.py): `backend/app.py`
- [Ownership proof](https://github.com/maharikha/campus-lost-found/blob/main/backend/verify.py): `backend/verify.py`

### Matching services

- [Report enrichment](https://github.com/maharikha/campus-lost-found/blob/main/backend/enrich.py): `backend/enrich.py`
- [Candidate ranking](https://github.com/maharikha/campus-lost-found/blob/main/backend/matcher.py): `backend/matcher.py`
- [Optional language model](https://github.com/maharikha/campus-lost-found/blob/main/backend/llm.py): `backend/llm.py`

### Persistence and alerts

- [SQLite records](https://github.com/maharikha/campus-lost-found/blob/main/backend/db.py): `backend/db.py`
- [Owner alerts](https://github.com/maharikha/campus-lost-found/blob/main/backend/notify.py): `backend/notify.py`

### Other components

- **Student or finder**
- **Desk staff**
- **Brevo SMTP**

## Connections

- Student or finder → App routing: uses (evidence: `frontend/src/App.jsx`)
- Desk staff → App routing: uses (evidence: `frontend/src/App.jsx`)
- App routing → Browse items: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Report item: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Match results: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Claim verification: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Staff desk: routes to (evidence: `frontend/src/App.jsx`)
- Browse items → API client: requests data (evidence: `frontend/src/pages/Home.jsx`)
- Report item → API client: submits report (evidence: `frontend/src/pages/ReportForm.jsx`)
- Report item → Report reminders: remembers report (evidence: `frontend/src/pages/ReportForm.jsx`)
- Match results → API client: loads matches (evidence: `frontend/src/pages/ReportPage.jsx`)
- Claim verification → API client: verifies claim (evidence: `frontend/src/pages/ClaimPage.jsx`)
- Staff desk → API client: requests desk data (evidence: `frontend/src/pages/Desk.jsx`)
- Browse items → Item cards: renders items (evidence: `frontend/src/pages/Home.jsx`)
- Match results → Item cards: renders matches (evidence: `frontend/src/pages/ReportPage.jsx`)
- Item cards → Display formatting: formats details (evidence: `frontend/src/components/TagCard.jsx`)
- API client → HTTP workflows: HTTP requests (evidence: `frontend/src/api.js`)
- HTTP workflows → Report enrichment: enriches reports (evidence: `backend/app.py`)
- HTTP workflows → Candidate ranking: ranks candidates (evidence: `backend/app.py`)
- HTTP workflows → Ownership proof: checks ownership (evidence: `backend/app.py`)
- HTTP workflows → SQLite records: reads and writes (evidence: `backend/app.py`)
- HTTP workflows → Owner alerts: alerts owners (evidence: `backend/app.py`)
- Report enrichment → Optional language model: requests extraction (evidence: `backend/enrich.py`)
- Owner alerts → Brevo SMTP: sends email (evidence: `README.md`)
- Student or finder → HTTP workflows: answers question
