How aary7406/lost-and-found-portal works
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: supabase.js Supabase · auth Auth API · admin Admin API · director Director API
Components 22
Next.js UI
App Router pages and shared presentation components
- Landing · Public home page and entrypoint
src/app/page.js - Login · Authentication screen
src/app/LogIn/page.js - Student Dash · Student request workflow UI
src/app/StudentDashboard/page.js - Admin Dash · Staff item and claim management UI
src/app/AdminDashboard/page.js - Director · Higher-privilege administration UI
src/app/Director/page.js - Director Dash · Director oversight and stats UI
src/app/DirectorDashboard/page.js - Search · Public or authenticated item lookup UI
src/app/search/page.js - Shared UI · Navigation, hero, search, dialogs, loaders, transitions, and toast UI
src/components
Next.js API
Route handlers for auth, dashboards, search, and ops
- Auth API · Login and director token verification
src/app/api/auth - Student API · Student lost-item request endpoints
src/app/api/student/requests - Admin API · Item, claim, student, user, and stats endpoints
src/app/api/admin - Director API · User administration and director stats
src/app/api/director - Search API · Item lookup endpoint
src/app/api/search/route.js - Ops API · Health, ping, setup, and Supabase checks
src/app/api/health
Shared Lib
Common Supabase, auth, and cache helpers
- Supabase · Shared Supabase client singleton
lib/supabase.js - Auth Helpers · JWT and auth support utilities
lib/supabase-auth.js - Cache · In-memory TTL response cache
lib/cache.js
DB Ops
Schema, seed, and migration scripts
- Schema · Supabase schema and migration scripts
scripts/supabase_schema.sql - Seed · Database seeding and bootstrap logic
scripts/seed.js - Migrations · Schema updates for lost items and related tables
scripts/update-items-schema.sql
Aux Services
Secondary Python entrypoints
- Flask API · Auxiliary Python entrypoint
api/flask/app.py - Flask Service · Secondary Python service entrypoint
flask_service/app.py
Connections 22
- 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