How jksanjay27/project-nextup works
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: services Domain services · api API routers · dashboard Workflows · lib Client logic
Components 18
Frontend
Next.js client with workflow-based screens and shared client logic.
- Next.js app · Authenticated and auth route shells for the placement-management client.
frontend/app - Auth screens · Login, register, and password recovery flows.
frontend/app/(auth) - Workflows · Dashboard, tracking, calendar, resume, profile, and AI toolkit views.
frontend/app/dashboard - Shared UI · Common visual and interaction components used across the client.
frontend/components - Client logic · API client, Zustand store, browser crypto, Supabase helpers, and AI client.
frontend/lib - Browser crypto · 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 · Main backend application and router assembly.
backend/app/main.py - API routers · Feature-oriented endpoints for auth, users, profiles, resumes, companies, applications, announcements, calendar, gmail, notifications, and AI.
backend/app/api - Domain services · Parsing, scoring, lifecycle, sync, validation, and AI services that implement the core workflows.
backend/app/services - Parsing pipeline · Email, PDF, and spreadsheet extraction that normalizes raw placement inputs into structured records.
backend/app/services/email_parser.py - Matching engine · Eligibility and match scoring for opportunities against student profile and skill data.
backend/app/services/match_scorer.py - Sync services · Gmail and calendar synchronization tied to authenticated sessions.
backend/app/services/gmail_sync.py - Database models · SQLAlchemy models and request/response schemas for persisted application state.
backend/app/models/models.py - Core infra · Configuration, database wiring, Redis, Gmail token cache, and security primitives.
backend/app/core - Attachment store · Local storage for parsed emails, PDFs, spreadsheets, and reprocessing artifacts.
backend/storage/attachments - Skills dictionary · Controlled skill vocabulary used for normalization and matching.
backend/skills_dictionary.json
Integrations
External triggers and auxiliary ingestion hooks.
- Supabase hook · Auxiliary email ingestion function bridging external events into the system.
supabase/functions/ingest-email/index.ts - Apps Script trigger · Google Apps Script hook used to trigger or relay email-driven automation.
apps-script/trigger.js
Connections 19
- 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.