# jksanjay27/project-nextup architecture

> Architecture diagram of the GitHub repository jksanjay27/project-nextup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jksanjay27/project-nextup
- Repository: https://github.com/jksanjay27/project-nextup

## Overview

1. **System shape**
   - This is a three-part placement-management platform: a **Next.js frontend**, a **FastAPI backend**, and a set of **integration/automation hooks** for Gmail, calendar sync, and email ingestion.
   - The backend is the main system of record; the frontend is mostly a thin, stateful client that handles encryption and UX.

2. **Frontend boundary**
   - The `frontend/` app is organized by user workflow: **auth**, **dashboard**, **tracking**, **calendar**, **resume**, **profile**, and **ai-toolkit**.
   - Shared UI lives in `components/` and shared client logic is in `lib/` (`api.ts`, `store.ts`, `crypto.ts`, `supabase.ts`, `ai-client.ts`).
   - Zustand appears to manage client state, while the app router/layout structure indicates separate shells for the main authenticated areas.

3. **Client-side privacy model**
   - A central architectural constraint is **zero-knowledge storage** for student profile and resume data.
   - Sensitive profile fields are encrypted in the browser using WebCrypto/AES-style client crypto before being sent to the backend.
   - The frontend therefore owns key derivation and ciphertext generation; the backend stores ciphertext rather than plaintext for these sensitive records.

4. **Backend API layer**
   - The FastAPI app in `backend/app/main.py` exposes feature-specific routers under `backend/app/api/`:
     - `auth`, `users`, `profiles`, `resumes`
     - `companies`, `applications`, `announcements`
     - `calendar`, `gmail`, `notifications`
     - `ai`
   - This is a service-oriented API boundary: each router maps to one product capability rather than a monolithic CRUD surface.

5. **Core backend services**
   - Business logic is split into `backend/app/services/` rather than living in the route handlers.
   - The most important service groups are:
     - **Parsing/extraction**: `email_parser`, `pdf_extractor`, `excel_parser`, `resume_parser`
     - **Matching/scoring**: `match_scorer`, `eligibility`, `priority_scorer`, `validator`
     - **Lifecycle/state**: `opportunity_lifecycle`, `stale_detector`
     - **Sync/automation**: `gmail_sync`, `calendar_sync`
     - **AI support**: `ai_service`
   - This separation suggests the API layer is thin and the services own the domain rules.

6. **Placement ingestion pipeline**
   - The core data flow is from **CDC Gmail/attachments → parsing services → normalized announcements/applications/events**.
   - Placement emails are parsed for role, stipend/CTC, deadlines, eligibility, and links.
   - Attachments such as PDFs and Excel shortlists are stored under `backend/storage/attachments/` for processing and traceability, then parsed into structured records.

7. **Matching and eligibility logic**
   - A distinct scoring layer compares student profile data against opportunity requirements.
   - `eligibility.py`, `match_scorer.py`, and `priority_scorer.py` indicate two related concerns:
     - whether a student qualifies
     - how well a drive matches the student’s profile/skills
   - The repository includes `skills_dictionary.json`, implying a controlled vocabulary for skill matching and normalization.

8. **Gmail and session-dependent automation**
   - The system integrates with Google Gmail/OAuth and appears to sync only while a user session is active.
   - `backend/app/core/gmail_token_cache.py` and `backend/app/core/redis.py` indicate an in-memory/session cache layer used to hold sensitive session material and support background sync.
   - This is a key boundary: sync is not a blind always-on daemon; it is tied to authenticated user activity.

9. **Persistence and infrastructure**
   - `backend/app/core/database.py` plus `backend/app/models/models.py` and `schemas.py` show a conventional API stack with ORM models and request/response schemas.
   - The repository supports relational storage via SQLAlchemy, with local storage for parsed files and Redis for ephemeral session/cache state.
   - `backend/Dockerfile`, `docker-compose.yml`, and `backend/requirements.txt` indicate containerized deployment.

10. **Notification and calendar surfaces**
   - `notifications`, `calendar`, and `announcements` are first-class domain objects, not just UI views.
   - The frontend dashboard/tracking/calendar pages consume these objects to show deadlines, shortlist results, application state, and scheduled events.
   - Calendar sync and ICS-style event handling are part of the backend service layer rather than the frontend alone.

11. **Resume ingestion path**
   - The `resume` workflow is treated as a separate parsing pipeline from announcements.
   - Resume PDFs are extracted with backend services, transformed into structured profile data, then encrypted client-side before persistence.
   - The frontend can use this parsed data to auto-populate the user profile, which reinforces the client-owned secret boundary.

12. **External integration hooks**
   - There are two non-core integration entry points outside the main FastAPI app:
     - `supabase/functions/ingest-email/index.ts`
     - `apps-script/trigger.js`
   - These suggest auxiliary email ingestion/trigger flows, likely used to bridge external mail events into the system.
   - They are adjuncts to the main backend, not the primary domain engine.

13. **Operational scripts and migration layer**
   - The many `migrate_*.py`, `reprocess_all.py`, and `scratch_*` files are maintenance and backfill tooling.
   - Architecturally, these scripts imply the data model and parser logic have evolved over time and need replay/reingestion support.
   - They are operational boundaries, not user-facing features.

14. **Overall data flow to diagram**
   - Primary flow: **browser login/encryption → FastAPI auth/API → database/cache/storage**.
   - Ingestion flow: **Gmail/attachments → sync/parsing services → normalized opportunities/applications/notifications → frontend dashboards**.
   - Auxiliary flow: **resume/profile data created in browser → encrypted payload stored server-side → used for matching and eligibility checks**.

Main entry points: [`backend/app/services`](https://github.com/jksanjay27/project-nextup/tree/main/backend/app/services) (Domain services), [`backend/app/api`](https://github.com/jksanjay27/project-nextup/tree/main/backend/app/api) (API routers), [`frontend/app/dashboard`](https://github.com/jksanjay27/project-nextup/tree/main/frontend/app/dashboard) (Workflows), [`frontend/lib`](https://github.com/jksanjay27/project-nextup/tree/main/frontend/lib) (Client logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Next.js app<br/>ui shell"]
  node_frontend_auth["Auth screens<br/>auth UI"]
  node_frontend_workflows["Workflows<br/>feature UI"]
  node_frontend_shared["Shared UI<br/>components"]
  node_frontend_clientlib["Client logic<br/>state/api/crypto"]
  node_frontend_crypto{{"Browser crypto<br/>zero-knowledge<br/>[crypto.ts]"}}
end

subgraph group_backend["Backend"]
  node_backend_app["FastAPI app<br/>api host<br/>[main.py]"]
  node_backend_routers["API routers<br/>HTTP API"]
  node_backend_services["Domain services<br/>business logic"]
  node_backend_ingest["Parsing pipeline<br/>ingestion<br/>[email_parser.py]"]
  node_backend_match{{"Matching engine<br/>scoring<br/>[match_scorer.py]"}}
  node_backend_sync["Sync services<br/>automation<br/>[gmail_sync.py]"]
  node_backend_db[("Database models<br/>orm/schema<br/>[models.py]")]
  node_backend_core["Core infra<br/>config/cache/security"]
  node_backend_storage["Attachment store<br/>file storage"]
  node_backend_skills["Skills dictionary<br/>vocabulary"]
end

subgraph group_integrations["Integrations"]
  node_integration_supabase["Supabase hook<br/>external ingest<br/>[index.ts]"]
  node_integration_apps_script["Apps Script trigger<br/>external trigger<br/>[trigger.js]"]
end

node_frontend_app -->|"routes"| node_frontend_auth
node_frontend_app -->|"routes"| node_frontend_workflows
node_frontend_workflows -->|"uses"| node_frontend_shared
node_frontend_workflows -->|"uses"| node_frontend_clientlib
node_frontend_clientlib -->|"encrypts"| node_frontend_crypto
node_frontend_clientlib -->|"calls"| node_backend_routers
node_backend_app -->|"mounts"| node_backend_routers
node_backend_routers -->|"delegates"| node_backend_services
node_backend_services -->|"parses"| node_backend_ingest
node_backend_services -->|"scores"| node_backend_match
node_backend_services -->|"syncs"| node_backend_sync
node_backend_services -->|"persists"| node_backend_db
node_backend_services -->|"reads/writes"| node_backend_storage
node_backend_services -->|"normalizes"| node_backend_skills
node_backend_core -->|"connects"| node_backend_db
node_backend_core -->|"supports"| node_backend_sync
node_backend_routers -->|"depends on"| node_backend_core
node_integration_supabase -->|"feeds"| node_backend_ingest
node_integration_apps_script -->|"triggers"| node_backend_sync

click node_frontend_app "https://github.com/jksanjay27/project-nextup/tree/main/frontend/app"
click node_frontend_auth "https://github.com/jksanjay27/project-nextup/tree/main/frontend/app/(auth)"
click node_frontend_workflows "https://github.com/jksanjay27/project-nextup/tree/main/frontend/app/dashboard"
click node_frontend_shared "https://github.com/jksanjay27/project-nextup/tree/main/frontend/components"
click node_frontend_clientlib "https://github.com/jksanjay27/project-nextup/tree/main/frontend/lib"
click node_frontend_crypto "https://github.com/jksanjay27/project-nextup/blob/main/frontend/lib/crypto.ts"
click node_backend_app "https://github.com/jksanjay27/project-nextup/blob/main/backend/app/main.py"
click node_backend_routers "https://github.com/jksanjay27/project-nextup/tree/main/backend/app/api"
click node_backend_services "https://github.com/jksanjay27/project-nextup/tree/main/backend/app/services"
click node_backend_ingest "https://github.com/jksanjay27/project-nextup/blob/main/backend/app/services/email_parser.py"
click node_backend_match "https://github.com/jksanjay27/project-nextup/blob/main/backend/app/services/match_scorer.py"
click node_backend_sync "https://github.com/jksanjay27/project-nextup/blob/main/backend/app/services/gmail_sync.py"
click node_backend_db "https://github.com/jksanjay27/project-nextup/blob/main/backend/app/models/models.py"
click node_backend_core "https://github.com/jksanjay27/project-nextup/tree/main/backend/app/core"
click node_backend_storage "https://github.com/jksanjay27/project-nextup/tree/main/backend/storage/attachments"
click node_backend_skills "https://github.com/jksanjay27/project-nextup/blob/main/backend/skills_dictionary.json"
click node_integration_supabase "https://github.com/jksanjay27/project-nextup/blob/main/supabase/functions/ingest-email/index.ts"
click node_integration_apps_script "https://github.com/jksanjay27/project-nextup/blob/main/apps-script/trigger.js"

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_app,node_frontend_auth,node_frontend_workflows,node_frontend_shared,node_frontend_clientlib,node_frontend_crypto toneBlue
class node_backend_app,node_backend_routers,node_backend_services,node_backend_ingest,node_backend_match,node_backend_sync,node_backend_db,node_backend_core,node_backend_storage,node_backend_skills toneAmber
class node_integration_supabase,node_integration_apps_script toneMint
```

## Components

### Frontend

Next.js client with workflow-based screens and shared client logic.

- [Next.js app](https://github.com/jksanjay27/project-nextup/tree/main/frontend/app): ui shell · Authenticated and auth route shells for the placement-management client. · `frontend/app`
- [Auth screens](https://github.com/jksanjay27/project-nextup/tree/main/frontend/app/(auth)): auth UI · Login, register, and password recovery flows. · `frontend/app/(auth)`
- [Workflows](https://github.com/jksanjay27/project-nextup/tree/main/frontend/app/dashboard): feature UI · Dashboard, tracking, calendar, resume, profile, and AI toolkit views. · `frontend/app/dashboard`
- [Shared UI](https://github.com/jksanjay27/project-nextup/tree/main/frontend/components): components · Common visual and interaction components used across the client. · `frontend/components`
- [Client logic](https://github.com/jksanjay27/project-nextup/tree/main/frontend/lib): state/api/crypto · API client, Zustand store, browser crypto, Supabase helpers, and AI client. · `frontend/lib`
- [Browser crypto](https://github.com/jksanjay27/project-nextup/blob/main/frontend/lib/crypto.ts): zero-knowledge · Client-side encryption and key handling for sensitive profile and resume fields. · `frontend/lib/crypto.ts`

### Backend

FastAPI API, domain services, persistence, and ingestion pipelines.

- [FastAPI app](https://github.com/jksanjay27/project-nextup/blob/main/backend/app/main.py): api host · Main backend application and router assembly. · `backend/app/main.py`
- [API routers](https://github.com/jksanjay27/project-nextup/tree/main/backend/app/api): HTTP API · Feature-oriented endpoints for auth, users, profiles, resumes, companies, applications, announcements, calendar, gmail, notifications, and AI. · `backend/app/api`
- [Domain services](https://github.com/jksanjay27/project-nextup/tree/main/backend/app/services): business logic · Parsing, scoring, lifecycle, sync, validation, and AI services that implement the core workflows. · `backend/app/services`
- [Parsing pipeline](https://github.com/jksanjay27/project-nextup/blob/main/backend/app/services/email_parser.py): ingestion · Email, PDF, and spreadsheet extraction that normalizes raw placement inputs into structured records. · `backend/app/services/email_parser.py`
- [Matching engine](https://github.com/jksanjay27/project-nextup/blob/main/backend/app/services/match_scorer.py): scoring · Eligibility and match scoring for opportunities against student profile and skill data. · `backend/app/services/match_scorer.py`
- [Sync services](https://github.com/jksanjay27/project-nextup/blob/main/backend/app/services/gmail_sync.py): automation · Gmail and calendar synchronization tied to authenticated sessions. · `backend/app/services/gmail_sync.py`
- [Database models](https://github.com/jksanjay27/project-nextup/blob/main/backend/app/models/models.py): orm/schema · SQLAlchemy models and request/response schemas for persisted application state. · `backend/app/models/models.py`
- [Core infra](https://github.com/jksanjay27/project-nextup/tree/main/backend/app/core): config/cache/security · Configuration, database wiring, Redis, Gmail token cache, and security primitives. · `backend/app/core`
- [Attachment store](https://github.com/jksanjay27/project-nextup/tree/main/backend/storage/attachments): file storage · Local storage for parsed emails, PDFs, spreadsheets, and reprocessing artifacts. · `backend/storage/attachments`
- [Skills dictionary](https://github.com/jksanjay27/project-nextup/blob/main/backend/skills_dictionary.json): vocabulary · Controlled skill vocabulary used for normalization and matching. · `backend/skills_dictionary.json`

### Integrations

External triggers and auxiliary ingestion hooks.

- [Supabase hook](https://github.com/jksanjay27/project-nextup/blob/main/supabase/functions/ingest-email/index.ts): external ingest · Auxiliary email ingestion function bridging external events into the system. · `supabase/functions/ingest-email/index.ts`
- [Apps Script trigger](https://github.com/jksanjay27/project-nextup/blob/main/apps-script/trigger.js): external trigger · Google Apps Script hook used to trigger or relay email-driven automation. · `apps-script/trigger.js`

## Connections

- Next.js app → Auth screens: routes · Public auth workflow screens.
- Next.js app → Workflows: routes · Authenticated product surfaces.
- Workflows → Shared UI: uses · Shared UI components power the workflow screens.
- Workflows → Client logic: uses · Client screens consume API, state, and helper logic.
- Client logic → Browser crypto: encrypts · Sensitive fields are encrypted in the browser before upload.
- Client logic → API routers: calls · Frontend talks to backend feature APIs.
- FastAPI app → API routers: mounts · Main application wires the feature routers.
- API routers → Domain services: delegates · Route handlers defer business logic to services.
- Domain services → Parsing pipeline: parses · Email and attachment parsing turn raw inputs into structured records.
- Domain services → Matching engine: scores · Eligibility and match scoring compare profiles to opportunities.
- Domain services → Sync services: syncs · Background sync services integrate Gmail and calendar activity.
- Domain services → Database models: persists · Structured domain objects are stored through ORM/schema layer.
- Domain services → Attachment store: reads/writes · Parsed attachments and replay artifacts are kept on local storage.
- Domain services → Skills dictionary: normalizes · Skill matching uses the controlled vocabulary.
- Core infra → Database models: connects · Database and ORM infrastructure live in core wiring.
- Core infra → Sync services: supports · Redis and token cache support session-bound automation.
- API routers → Core infra: depends on · API layer relies on config, security, and persistence plumbing.
- Supabase hook → Parsing pipeline: feeds · External ingestion hook forwards email events into parsing flows.
- Apps Script trigger → Sync services: triggers · Apps Script initiates email-driven automation and sync.