# aary7406/lost-and-found-portal architecture

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

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

## Overview

1. **Primary shape of the repo**
   This is a **Next.js 16 App Router monorepo-style application** where the frontend and server API live together in `src/app`. The main production path is: browser UI → Next.js route handlers → Supabase PostgreSQL. The repo is centered on a lost-and-found workflow for three roles: **student**, **admin**, and **director**.

2. **User-facing application surfaces**
   The UI is split into page-level areas under `src/app/`:
   - `page.js` for the landing page
   - `LogIn` for authentication
   - `StudentDashboard` for student requests
   - `AdminDashboard` for staff item/claim management
   - `DirectorDashboard` and `Director` for higher-privilege oversight
   - `search` for public or authenticated item lookup  
   These pages are composed from reusable components in `src/components/`.

3. **Reusable presentation layer**
   `src/components/` holds the shared UI building blocks: navigation, hero/CTA sections, stats, search widgets, toast notifications, confirm dialogs, date pickers, transitions, loaders, and icon components. Styling is primarily **CSS Modules**. This is a presentation layer only; the business logic lives in route handlers and Supabase access code.

4. **API boundary**
   The backend is implemented as **Next.js API route handlers** in `src/app/api/`. The routes are grouped by domain:
   - `api/auth/*` for login and director token verification
   - `api/student/requests` for student-created lost-item reports
   - `api/admin/*` for items, claims, students, users, and stats
   - `api/director/*` for user administration and director stats
   - `api/search` for item lookup
   - `api/health`, `api/ping`, and `api/setup/director` for operational/setup concerns  
   This is a single application boundary, not a separate backend service.

5. **Authentication and authorization flow**
   Authentication is JWT-based, with passwords hashed using **bcryptjs**. The login endpoints query the user store, validate credentials, and issue signed tokens using a shared secret. Role-based access is enforced at the API layer and reflected in the UI routes. The README indicates tokens are stored client-side and used to gate access to dashboards and protected endpoints.

6. **Domain workflows**
   The core business objects are **users**, **items**, **claims**, and **student requests**. The admin area appears to own the item lifecycle:
   - create/update/delete items
   - manage claims
   - inspect students and users
   - read aggregate stats  
   The item model supports a status workflow such as lost/found/claimed/returned and uses unique item identifiers. The student area focuses on filing and viewing requests, while the director area focuses on user management and high-level statistics.

7. **Data access layer**
   The repo’s shared backend utilities live in `lib/`:
   - `supabase.js` is the central Supabase client singleton
   - `supabase-auth.js` contains auth-related helpers
   - `cache.js` adds an in-memory TTL cache for API responses  
   This means most route handlers likely follow the same pattern: validate request → use shared Supabase client → optionally use cache → return JSON.

8. **Database and external system**
   The application uses **Supabase PostgreSQL** as its primary data store. The README and SQL scripts show relational tables such as `users` and `lost_items`, plus schema/migration files in `scripts/`. Supabase also implies database-level security boundaries such as **RLS** and foreign keys, so authorization is not only application-side.

9. **Operational and deployment concerns**
   The repo includes `vercel.json`, which suggests deployment on **Vercel** with Next.js serverless route handlers. Environment variables are used for Supabase URL, service-role key, and JWT secret. There are lightweight operational endpoints like `/api/health`, `/api/health/supabase`, and `/api/ping` for runtime checks.

10. **Bootstrap, migrations, and seed data**
   `scripts/` contains SQL and seed utilities for initializing the database and evolving schemas. That indicates the repo expects controlled setup outside normal user traffic: schema creation, updates, and initial data seeding before the app is used. The README’s setup flow also references a director-seeding step.

11. **Secondary Python service boundary**
   In addition to the Next.js stack, the repo contains two Flask entrypoints: `api/flask/app.py` and `flask_service/app.py` with a Python `requirements.txt`. Based on the tree alone, these look like **auxiliary or experimental service boundaries**, not the main application path. If you draw the architecture, keep them separate from the Next.js/Supabase runtime unless you confirm they are actively invoked.

12. **What matters most for an architecture diagram**
   The accurate high-level diagram is: **browser pages and dashboards** feeding into **Next.js route handlers**, which delegate to **shared auth/cache/Supabase helpers**, which in turn talk to **Supabase PostgreSQL**. Around that core are schema/seed scripts, operational health routes, and a small set of reusable UI and transition components that support the front end.

Main entry points: [`lib/supabase.js`](https://github.com/aary7406/lost-and-found-portal/blob/main/lib/supabase.js) (Supabase), [`src/app/api/auth`](https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/auth) (Auth API), [`src/app/api/admin`](https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/admin) (Admin API), [`src/app/api/director`](https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/director) (Director API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js UI"]
  node_app_landing["Landing<br/>page<br/>[page.js]"]
  node_app_login["Login<br/>page<br/>[page.js]"]
  node_app_student["Student Dash<br/>page<br/>[page.js]"]
  node_app_admin["Admin Dash<br/>page<br/>[page.js]"]
  node_app_director["Director<br/>page<br/>[page.js]"]
  node_app_director_dash["Director Dash<br/>page<br/>[page.js]"]
  node_app_search["Search<br/>page<br/>[page.js]"]
  node_ui_components["Shared UI<br/>components"]
end

subgraph group_backend["Next.js API"]
  node_api_auth["Auth API<br/>routes"]
  node_api_student["Student API<br/>routes"]
  node_api_admin["Admin API<br/>routes"]
  node_api_director["Director API<br/>routes"]
  node_api_search["Search API<br/>route<br/>[route.js]"]
  node_api_ops["Ops API<br/>routes"]
end

subgraph group_shared["Shared Lib"]
  node_supabase_lib[("Supabase<br/>client<br/>[supabase.js]")]
  node_auth_lib["Auth Helpers<br/>[supabase-auth.js]"]
  node_cache_lib["Cache<br/>[cache.js]"]
end

subgraph group_data["DB Ops"]
  node_db_schema["Schema<br/>sql"]
  node_db_seed["Seed<br/>script<br/>[seed.js]"]
  node_db_migrations["Migrations<br/>sql"]
end

subgraph group_aux["Aux Services"]
  node_flask_api["Flask API<br/>python service<br/>[app.py]"]
  node_flask_service["Flask Service<br/>python service<br/>[app.py]"]
end

node_app_landing -->|"compose"| node_ui_components
node_app_login -->|"auth"| node_api_auth
node_app_student -->|"requests"| node_api_student
node_app_admin -->|"manage"| node_api_admin
node_app_director -->|"admin"| node_api_director
node_app_director_dash -->|"stats"| node_api_director
node_app_search -->|"lookup"| node_api_search
node_ui_components -.->|"ui helpers"| node_cache_lib
node_api_auth -->|"verify"| node_auth_lib
node_api_auth -->|"users"| node_supabase_lib
node_api_student -->|"data"| node_supabase_lib
node_api_admin -->|"data"| node_supabase_lib
node_api_admin -.->|"cache"| node_cache_lib
node_api_director -->|"data"| node_supabase_lib
node_api_search -->|"query"| node_supabase_lib
node_api_ops -->|"health"| node_supabase_lib
node_api_ops -.->|"setup"| node_db_seed
node_supabase_lib -.->|"backing schema"| node_db_schema
node_db_schema -.->|"evolves"| node_db_migrations
node_db_seed -.->|"initializes"| node_db_schema
node_flask_api -.->|"optional backend"| node_supabase_lib
node_flask_service -.->|"optional backend"| node_supabase_lib

click node_app_landing "https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/page.js"
click node_app_login "https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/LogIn/page.js"
click node_app_student "https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/StudentDashboard/page.js"
click node_app_admin "https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/AdminDashboard/page.js"
click node_app_director "https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/Director/page.js"
click node_app_director_dash "https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/DirectorDashboard/page.js"
click node_app_search "https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/search/page.js"
click node_ui_components "https://github.com/aary7406/lost-and-found-portal/tree/main/src/components"
click node_api_auth "https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/auth"
click node_api_student "https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/student/requests"
click node_api_admin "https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/admin"
click node_api_director "https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/director"
click node_api_search "https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/api/search/route.js"
click node_api_ops "https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/health"
click node_supabase_lib "https://github.com/aary7406/lost-and-found-portal/blob/main/lib/supabase.js"
click node_auth_lib "https://github.com/aary7406/lost-and-found-portal/blob/main/lib/supabase-auth.js"
click node_cache_lib "https://github.com/aary7406/lost-and-found-portal/blob/main/lib/cache.js"
click node_db_schema "https://github.com/aary7406/lost-and-found-portal/blob/main/scripts/supabase_schema.sql"
click node_db_seed "https://github.com/aary7406/lost-and-found-portal/blob/main/scripts/seed.js"
click node_db_migrations "https://github.com/aary7406/lost-and-found-portal/blob/main/scripts/update-items-schema.sql"
click node_flask_api "https://github.com/aary7406/lost-and-found-portal/blob/main/api/flask/app.py"
click node_flask_service "https://github.com/aary7406/lost-and-found-portal/blob/main/flask_service/app.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_landing,node_app_login,node_app_student,node_app_admin,node_app_director,node_app_director_dash,node_app_search,node_ui_components toneBlue
class node_api_auth,node_api_student,node_api_admin,node_api_director,node_api_search,node_api_ops toneAmber
class node_supabase_lib,node_auth_lib,node_cache_lib toneMint
class node_db_schema,node_db_seed,node_db_migrations toneRose
class node_flask_api,node_flask_service toneIndigo
```

## Components

### Next.js UI

App Router pages and shared presentation components

- [Landing](https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/page.js): page · Public home page and entrypoint · `src/app/page.js`
- [Login](https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/LogIn/page.js): page · Authentication screen · `src/app/LogIn/page.js`
- [Student Dash](https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/StudentDashboard/page.js): page · Student request workflow UI · `src/app/StudentDashboard/page.js`
- [Admin Dash](https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/AdminDashboard/page.js): page · Staff item and claim management UI · `src/app/AdminDashboard/page.js`
- [Director](https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/Director/page.js): page · Higher-privilege administration UI · `src/app/Director/page.js`
- [Director Dash](https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/DirectorDashboard/page.js): page · Director oversight and stats UI · `src/app/DirectorDashboard/page.js`
- [Search](https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/search/page.js): page · Public or authenticated item lookup UI · `src/app/search/page.js`
- [Shared UI](https://github.com/aary7406/lost-and-found-portal/tree/main/src/components): components · Navigation, hero, search, dialogs, loaders, transitions, and toast UI · `src/components`

### Next.js API

Route handlers for auth, dashboards, search, and ops

- [Auth API](https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/auth): routes · Login and director token verification · `src/app/api/auth`
- [Student API](https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/student/requests): routes · Student lost-item request endpoints · `src/app/api/student/requests`
- [Admin API](https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/admin): routes · Item, claim, student, user, and stats endpoints · `src/app/api/admin`
- [Director API](https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/director): routes · User administration and director stats · `src/app/api/director`
- [Search API](https://github.com/aary7406/lost-and-found-portal/blob/main/src/app/api/search/route.js): route · Item lookup endpoint · `src/app/api/search/route.js`
- [Ops API](https://github.com/aary7406/lost-and-found-portal/tree/main/src/app/api/health): routes · Health, ping, setup, and Supabase checks · `src/app/api/health`

### Shared Lib

Common Supabase, auth, and cache helpers

- [Supabase](https://github.com/aary7406/lost-and-found-portal/blob/main/lib/supabase.js): client · Shared Supabase client singleton · `lib/supabase.js`
- [Auth Helpers](https://github.com/aary7406/lost-and-found-portal/blob/main/lib/supabase-auth.js): helpers · JWT and auth support utilities · `lib/supabase-auth.js`
- [Cache](https://github.com/aary7406/lost-and-found-portal/blob/main/lib/cache.js): cache · In-memory TTL response cache · `lib/cache.js`

### DB Ops

Schema, seed, and migration scripts

- [Schema](https://github.com/aary7406/lost-and-found-portal/blob/main/scripts/supabase_schema.sql): sql · Supabase schema and migration scripts · `scripts/supabase_schema.sql`
- [Seed](https://github.com/aary7406/lost-and-found-portal/blob/main/scripts/seed.js): script · Database seeding and bootstrap logic · `scripts/seed.js`
- [Migrations](https://github.com/aary7406/lost-and-found-portal/blob/main/scripts/update-items-schema.sql): sql · Schema updates for lost items and related tables · `scripts/update-items-schema.sql`

### Aux Services

Secondary Python entrypoints

- [Flask API](https://github.com/aary7406/lost-and-found-portal/blob/main/api/flask/app.py): python service · Auxiliary Python entrypoint · `api/flask/app.py`
- [Flask Service](https://github.com/aary7406/lost-and-found-portal/blob/main/flask_service/app.py): python service · Secondary Python service entrypoint · `flask_service/app.py`

## Connections

- Landing → Shared UI: compose · Landing page is built from shared presentation components
- Login → Auth API: auth · Login screen submits credentials to auth routes
- Student Dash → Student API: requests · Student dashboard creates and reads requests
- Admin Dash → Admin API: manage · Admin dashboard manages items, claims, students, and users
- Director → Director API: admin · Director screen drives privileged user administration
- Director Dash → Director API: stats · Director dashboard reads oversight endpoints
- Search → Search API: lookup · Search page queries item lookup
- Shared UI → Cache: ui helpers · Shared UI may reuse lightweight app helpers
- Auth API → Auth Helpers: verify · Authentication routes use shared auth helpers
- Auth API → Supabase: users · Auth routes query the Supabase-backed user store
- Student API → Supabase: data · Student requests are persisted through Supabase
- Admin API → Supabase: data · Admin operations read and write domain records
- Admin API → Cache: cache · Admin endpoints may use cached responses
- Director API → Supabase: data · Director endpoints operate on shared persistence
- Search API → Supabase: query · Search endpoint reads item data from Supabase
- Ops API → Supabase: health · Operational checks include Supabase connectivity
- Ops API → Seed: setup · Setup routes support bootstrap flows
- Supabase → Schema: backing schema · Shared client targets the repository's Supabase schema
- Schema → Migrations: evolves · Migrations extend the base schema
- Seed → Schema: initializes · Seed logic assumes the core schema is present
- Flask API → Supabase: optional backend · Auxiliary Python service may also access Supabase
- Flask Service → Supabase: optional backend · Secondary Python service may also access Supabase
