# alamin147/lost-and-found architecture

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

- Interactive diagram: https://gitdiagram.com/alamin147/lost-and-found
- Repository: https://github.com/alamin147/lost-and-found

## Overview

Lost & Found is a full-stack community platform: users authenticate, report lost or found belongings, search listings, and submit claims; administrators manage listings, claims, users, categories, and statistics. The frontend routes users into public, personal, and administrative views, while the Express API dispatches requests to domain controllers and services backed by Prisma. AI search reads eligible listings and asks Gemini to rank matches, with a text-search fallback. Backend routing and several controller/service interactions are sampled; frontend API-call wiring and some unsampled service internals are not shown, so those links are omitted.

Main entry points: [`server/src/app/routes/routes.ts`](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/routes/routes.ts) (API route dispatch), [`server/src/app/config/prisma.ts`](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/config/prisma.ts) (PostgreSQL via Prisma), [`frontend/src/main.tsx`](https://github.com/alamin147/lost-and-found/blob/main/frontend/src/main.tsx) (React entry and routes), [`server/src/app/modules/aiSearch/aiSearch.service.ts`](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/aiSearch/aiSearch.service.ts) (AI matching and fallback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_frontend["React entry and routes<br/>[main.tsx]"]
  node_public_views["Browse and report"]
  node_account_views["Login and registration"]
  node_personal_views["Personal item and claim views"]
  node_admin_views["Admin dashboard"]
  node_client_api["Frontend API layer"]
end

subgraph group_api["API and identity"]
  node_server["Express application<br/>[app.ts]"]
  node_routes["API route dispatch<br/>[routes.ts]"]
  node_auth_controller["Authentication endpoints<br/>[auth.controller.ts]"]
  node_auth_service["Identity and account service<br/>[auth.service.ts]"]
  node_user_controller["User administration endpoints"]
end

subgraph group_items["Items and claims"]
  node_found_controller["Found item endpoints"]
  node_lost_controller["Lost item endpoints<br/>[lost.controller.ts]"]
  node_claim_controller["Claim endpoints"]
  node_category_controller["Category endpoints"]
end

subgraph group_operations["Administration and search"]
  node_ai_controller["AI search endpoint"]
  node_ai_service["AI matching and fallback"]
  node_stats["Admin statistics<br/>[adminStats.ts]"]
end

node_person(("User or admin"))
node_database[("PostgreSQL via Prisma<br/>[prisma.ts]")]
node_gemini{{"Google Gemini"}}

node_person -->|"uses"| node_frontend
node_frontend -->|"routes to"| node_public_views
node_frontend -->|"routes to"| node_account_views
node_frontend -->|"routes to"| node_personal_views
node_frontend -->|"routes to"| node_admin_views
node_person -->|"submits requests"| node_client_api
node_client_api -->|"API requests"| node_server
node_server -->|"mounts API"| node_routes
node_routes -->|"dispatches"| node_auth_controller
node_routes -->|"dispatches"| node_user_controller
node_routes -->|"dispatches"| node_found_controller
node_routes -->|"dispatches"| node_lost_controller
node_routes -->|"dispatches"| node_claim_controller
node_routes -->|"dispatches"| node_category_controller
node_routes -->|"dispatches"| node_ai_controller
node_routes -->|"dispatches"| node_stats
node_auth_controller -->|"calls"| node_auth_service
node_auth_service -->|"reads and writes"| node_database
node_found_controller -->|"service accesses"| node_database
node_lost_controller -->|"service accesses"| node_database
node_claim_controller -->|"service accesses"| node_database
node_category_controller -->|"service accesses"| node_database
node_user_controller -->|"service accesses"| node_database
node_ai_controller -->|"calls"| node_ai_service
node_ai_service -->|"loads listings"| node_database
node_ai_service -.->|"requests matches"| node_gemini
node_stats -->|"reads metrics"| node_database

click node_frontend "https://github.com/alamin147/lost-and-found/blob/main/frontend/src/main.tsx"
click node_public_views "https://github.com/alamin147/lost-and-found/tree/main/frontend/src/pages"
click node_account_views "https://github.com/alamin147/lost-and-found/tree/main/frontend/src/pages"
click node_personal_views "https://github.com/alamin147/lost-and-found/tree/main/frontend/src/dashboard"
click node_admin_views "https://github.com/alamin147/lost-and-found/tree/main/frontend/src/dashboard/pages"
click node_client_api "https://github.com/alamin147/lost-and-found/tree/main/frontend/src/redux/api"
click node_server "https://github.com/alamin147/lost-and-found/blob/main/server/src/app.ts"
click node_routes "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/routes/routes.ts"
click node_auth_controller "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/auth/auth.controller.ts"
click node_auth_service "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/auth/auth.service.ts"
click node_user_controller "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/user/user.controllers.ts"
click node_found_controller "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/foundItems/foundItem.controller.ts"
click node_lost_controller "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/lostItem/lost.controller.ts"
click node_claim_controller "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/claim/claim.controller.ts"
click node_category_controller "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/itemCategory/itemcategory.controller.ts"
click node_ai_controller "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/aiSearch/aiSearch.controller.ts"
click node_ai_service "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/aiSearch/aiSearch.service.ts"
click node_stats "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/utils/adminStats.ts"
click node_database "https://github.com/alamin147/lost-and-found/blob/main/server/src/app/config/prisma.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_frontend,node_public_views,node_account_views,node_personal_views,node_admin_views,node_client_api,node_person toneBlue
class node_server,node_routes,node_auth_controller,node_auth_service,node_user_controller,node_database toneAmber
class node_found_controller,node_lost_controller,node_claim_controller,node_category_controller toneMint
class node_ai_controller,node_ai_service,node_stats toneRose
class node_gemini toneIndigo
```

## Components

### Web application

- [React entry and routes](https://github.com/alamin147/lost-and-found/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Browse and report](https://github.com/alamin147/lost-and-found/tree/main/frontend/src/pages): `frontend/src/pages`
- [Login and registration](https://github.com/alamin147/lost-and-found/tree/main/frontend/src/pages): `frontend/src/pages`
- [Personal item and claim views](https://github.com/alamin147/lost-and-found/tree/main/frontend/src/dashboard): `frontend/src/dashboard`
- [Admin dashboard](https://github.com/alamin147/lost-and-found/tree/main/frontend/src/dashboard/pages): `frontend/src/dashboard/pages`
- [Frontend API layer](https://github.com/alamin147/lost-and-found/tree/main/frontend/src/redux/api): `frontend/src/redux/api`

### API and identity

- [Express application](https://github.com/alamin147/lost-and-found/blob/main/server/src/app.ts): `server/src/app.ts`
- [API route dispatch](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/routes/routes.ts): `server/src/app/routes/routes.ts`
- [Authentication endpoints](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/auth/auth.controller.ts): `server/src/app/auth/auth.controller.ts`
- [Identity and account service](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/auth/auth.service.ts): `server/src/app/auth/auth.service.ts`
- [User administration endpoints](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/user/user.controllers.ts): `server/src/app/modules/user/user.controllers.ts`

### Items and claims

- [Found item endpoints](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/foundItems/foundItem.controller.ts): `server/src/app/modules/foundItems/foundItem.controller.ts`
- [Lost item endpoints](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/lostItem/lost.controller.ts): `server/src/app/modules/lostItem/lost.controller.ts`
- [Claim endpoints](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/claim/claim.controller.ts): `server/src/app/modules/claim/claim.controller.ts`
- [Category endpoints](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/itemCategory/itemcategory.controller.ts): `server/src/app/modules/itemCategory/itemcategory.controller.ts`

### Administration and search

- [AI search endpoint](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/aiSearch/aiSearch.controller.ts): `server/src/app/modules/aiSearch/aiSearch.controller.ts`
- [AI matching and fallback](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/modules/aiSearch/aiSearch.service.ts): `server/src/app/modules/aiSearch/aiSearch.service.ts`
- [Admin statistics](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/utils/adminStats.ts): `server/src/app/utils/adminStats.ts`

### Other components

- **User or admin**
- [PostgreSQL via Prisma](https://github.com/alamin147/lost-and-found/blob/main/server/src/app/config/prisma.ts): `server/src/app/config/prisma.ts`
- **Google Gemini**

## Connections

- User or admin → React entry and routes: uses
- React entry and routes → Browse and report: routes to
- React entry and routes → Login and registration: routes to
- React entry and routes → Personal item and claim views: routes to
- React entry and routes → Admin dashboard: routes to
- User or admin → Frontend API layer: submits requests
- Frontend API layer → Express application: API requests
- Express application → API route dispatch: mounts API
- API route dispatch → Authentication endpoints: dispatches
- API route dispatch → User administration endpoints: dispatches
- API route dispatch → Found item endpoints: dispatches
- API route dispatch → Lost item endpoints: dispatches
- API route dispatch → Claim endpoints: dispatches
- API route dispatch → Category endpoints: dispatches
- API route dispatch → AI search endpoint: dispatches
- API route dispatch → Admin statistics: dispatches
- Authentication endpoints → Identity and account service: calls
- Identity and account service → PostgreSQL via Prisma: reads and writes
- Found item endpoints → PostgreSQL via Prisma: service accesses
- Lost item endpoints → PostgreSQL via Prisma: service accesses
- Claim endpoints → PostgreSQL via Prisma: service accesses
- Category endpoints → PostgreSQL via Prisma: service accesses
- User administration endpoints → PostgreSQL via Prisma: service accesses
- AI search endpoint → AI matching and fallback: calls
- AI matching and fallback → PostgreSQL via Prisma: loads listings
- AI matching and fallback → Google Gemini: requests matches
- Admin statistics → PostgreSQL via Prisma: reads metrics