How mahamudul-hasan-cse/gradpilot-ai works
1. Overall shape
- GradPilot AI is a two-app monorepo: a FastAPI backend in apps/api and a Next.js frontend in apps/web.
- A small packages/shared package provides shared TypeScript types/utilities for the frontend side.
- The backend owns persistence, domain logic, ingestion, and AI orchestration; the frontend owns UI, session handling, and API consumption.
2. Primary runtime boundary
- The frontend talks to the backend over HTTP using the backend’s /api/v1 endpoints.
- The backend exposes a separate health endpoint and OpenAPI docs.
- Authentication is split: backend issues/validates app auth, while the frontend uses NextAuth and must share AUTH_SECRET with the backend environment.
3. Backend request pipeline
- The API layer is organized by domain under apps/api/app/api/v1/endpoints.
- Request flow is: endpoint → service → repository → SQLAlchemy model → PostgreSQL.
- Schemas in app/schemas define API contracts, while app/models define persisted entities and app/repositories isolate database access.
4. Core data model
- The main persistent entities are centered on students, universities, scholarships, applications, documents, recommendations, and AI-generated artifacts.
- Additional tables support specialized features such as chat sessions, document intelligence, digital twin state, SOP drafts, and application activity metadata.
- Alembic migrations show the product’s evolution from a basic schema into multiple feature domains.
5. Student profile and intelligence layer
- Profile-related endpoints and services compute readiness and recommendations from user-entered academic data.
- This layer feeds multiple downstream features: university matching, scholarship matching, AI planner tasks, and the dashboard widgets.
- profile_intelligence is a distinct service area, not just a CRUD profile store.
6. University and scholarship discovery
- Universities and scholarships are first-class catalog domains with seeded source data in apps/api/data/sources.
- Discovery and ranking services power filtering, ranking, and match-style views in the frontend.
- These flows are mostly read-heavy and rely on curated data plus scoring logic rather than user-generated content.
7. Recommendations and matching
- Recommendation logic is separated into its own service and repository layer, with dedicated scoring/explainer components.
- Scholarship matching has a parallel implementation with its own scoring and explanation path.
- These subsystems take profile and catalog data as input and return ranked, explainable results for dashboard widgets and detail pages.
8. AI advisor and knowledge platform
- Generative AI goes through a single backend integration around Google Gemini.
- The knowledge platform combines retrieval, ranking, query rewriting, citation generation, hallucination guards, and conversation memory.
- Retrieval is hybrid: semantic search, BM25, and reciprocal-rank fusion are all represented, indicating a multi-stage RAG-style pipeline.
- qdrant_store.py suggests vector storage is part of the architecture for semantic retrieval.
9. Document intelligence and uploads
- The document subsystem handles intake of student files such as transcripts, IELTS results, and CVs.
- Its pipeline includes extraction, OCR provider integration, classification, validation, deduplication, queueing, and synchronization into the digital twin.
- Local uploads are stored outside Git in an uploads/ directory; production is expected to use managed storage.
10. Application workspace
- Applications are not just a status list; they have a dedicated workspace with tasks, deadlines, progress, notes, documents, and activity tracking.
- Services under application_workspace compute analytics and workflow state for the student’s application journey.
- The frontend exposes this through dashboard views and per-application pages, including a Kanban-like tracker.
11. AI planner, digital twin, and SOP studio
- The AI planner generates personalized timelines, reminders, and task priorities from profile and application context.
- The digital twin subsystem aggregates events and profile/doc data into a continuously updated student representation.
- The SOP studio handles drafting, rewriting, grammar checking, plagiarism-related checks, tailoring, scoring, and export of statements of purpose.
- These are separate feature verticals but share the same underlying student and document state.
12. Frontend architecture
- The frontend uses the Next.js App Router with feature pages for dashboard, profile, universities, scholarships, documents, planner, timeline, applications, notifications, settings, admin, and auth.
- UI state is split between React Query for server data and Zustand for local client state.
- Shared layout components provide the app shell, sidebar, headers, theme support, and dashboard widgets.
- The frontend is the presentation layer only; it does not own business rules or persistence.
13. Operational concerns
- PostgreSQL is the main system of record, with Alembic handling schema migrations.
- Backend tests cover major domains individually, which suggests each feature area is intended to remain independently verifiable.
- Seed scripts populate catalog data such as universities, scholarships, and knowledge content for local development.
14. Key external dependencies
- Google Gemini API is the primary external AI dependency and affects advisor, rewriting, summarization, analysis, planner, and SOP features.
- PostgreSQL is the main persistence layer; Neon PostgreSQL is the recommended managed production option.
- The overall architecture is therefore: a database-backed FastAPI domain service layer, a Next.js presentation app, and AI-assisted feature services built around Gemini and retrieval infrastructure.
Main entry points: repositories Repositories · v1 API Router · app App Router · knowledge Knowledge Platform
Components 23
Backend API
FastAPI service with domain logic, persistence, AI orchestration, and ingestion.
- API Router · Versioned HTTP endpoints for auth, profile, discovery, universities, scholarships, documents, planner, AI, and applications.
apps/api/app/api/v1 - Domain Services · Backend business logic for profiles, recommendations, scholarships, universities, applications, AI, SOPs, and student workflows.
apps/api/app/services - Repositories · Persistence isolation layer for the backend domain models and workspace subdomains.
apps/api/app/repositories - Data Models · Persistent entities for students, universities, scholarships, applications, documents, knowledge, digital twin, planner, and SOP data.
apps/api/app/models - API Schemas · Request and response contracts shared across backend endpoints and service boundaries.
apps/api/app/schemas - Ingestion Pipeline · Pipeline for scraping, extracting, normalizing, deduplicating, and validating source data and uploads.
apps/api/app/ingestion - Knowledge Platform · Hybrid retrieval and LLM orchestration with query rewriting, citation generation, hallucination guards, memory, and Qdrant-backed vector search.
apps/api/app/services/knowledge - Profile Intelligence · Computes readiness, recommendations, and derived profile insights used by discovery, dashboard, and planner features.
apps/api/app/services/profile_intelligence - Recommendations · General recommendation and explainer logic for ranked matches and dashboard widgets.
apps/api/app/services/recommendation - Scholarship Matching · Scholarship-specific scoring and explanation path built on profile and catalog data.
apps/api/app/services/scholarship_recommendation - University Discovery · Read-heavy discovery, filtering, and ranking flows for university catalog data.
apps/api/app/services/university_discovery.py - Application Workspace · Application progress, tasks, deadlines, notes, documents, analytics, and activity tracking.
apps/api/app/services/application_workspace - Digital Twin · Continuously updated student representation combining profile, document, and event data.
apps/api/app/services/digital_twin - AI Planner · Generates personalized timelines, reminders, and task prioritization from profile and application context.
apps/api/app/services/ai_planner - SOP Studio · Drafting, rewriting, grammar, plagiarism, tailoring, scoring, and export for statements of purpose.
apps/api/app/services/sop_studio
Frontend App
Next.js presentation layer for student-facing and admin workflows.
- App Router · Frontend pages and route handlers for dashboard, profile, discovery, applications, admin, auth, and settings.
apps/web/src/app - UI Shell · Shared layout, dashboard widgets, and UI primitives that frame the frontend experience.
apps/web/src/components - Client State · Frontend data-fetching and local state management via React Query, Zustand, and auth hooks.
apps/web/src/lib - NextAuth · Frontend authentication route and session integration for user sign-in and app access.
apps/web/src/app/api/auth/[...nextauth]/route.ts
Shared Package
Cross-app TypeScript types and utilities.
- Shared Types · Shared frontend-side types and utilities consumed across the monorepo.
packages/shared/src/index.ts
External Systems
Datastores and third-party services used by the product.
- Gemini API · Primary generative AI dependency for advisor, rewriting, summarization, planning, and SOP features.
- PostgreSQL · System of record for users, profiles, universities, scholarships, applications, documents, and AI feature state.
- Qdrant · Vector retrieval storage used by semantic search in the knowledge platform.
Connections 31
- App Router → UI Shell: renders · Pages compose layout and dashboard components into user-facing screens.
- App Router → Client State: fetches · Frontend pages consume server data and local state through hooks and query client.
- NextAuth → Client State: sessions · NextAuth session state feeds client-side auth-aware UI behavior.
- App Router → API Router: HTTP /api/v1 · Frontend consumes backend endpoints for all major product flows.
- App Router → Shared Types: types · Frontend imports shared TypeScript types and utilities.
- API Router → API Schemas: contracts · Endpoints validate inputs and shape outputs through schemas.
- API Router → Domain Services: delegates · Route handlers hand off domain work to services.
- Domain Services → Repositories: persists · Services coordinate repository access instead of touching the database directly.
- Repositories → Data Models: maps · Repositories operate on SQLAlchemy entities and persistence records.
- Data Models → PostgreSQL: stores · Persistent domain state lives in PostgreSQL.
- Ingestion Pipeline → Data Models: loads · Ingested and normalized source data is written into domain tables.
- Ingestion Pipeline → PostgreSQL: syncs · Pipeline stages persist and deduplicate catalog and upload data.
- Profile Intelligence → Repositories: reads · Profile intelligence uses stored student and analysis data.
- Profile Intelligence → Recommendations: feeds · Derived readiness and profile signals power recommendations.
- Recommendations → Scholarship Matching: parallelizes · Scholarship matching runs as a sibling scoring path to general recommendations.
- Recommendations → Repositories: scores · Recommendation scoring combines profile and catalog data from repositories.
- University Discovery → Ingestion Pipeline: catalog source · Discovery relies on seeded university data and curated sources.
- University Discovery → Repositories: queries · Discovery and ranking read university catalog data through repositories.
- Scholarship Matching → Repositories: queries · Scholarship matching reads scholarships and profile context through repositories.
- Application Workspace → Repositories: tracks · Workspace services coordinate tasks, deadlines, notes, documents, and activity data.
- Application Workspace → Digital Twin: syncs · Application progress contributes to the student’s digital twin state.
- Digital Twin → Repositories: aggregates · Digital twin services combine events and persisted student/document data.
- AI Planner → Digital Twin: consumes · Planner uses the aggregated student state to generate priorities and timelines.
- AI Planner → Gemini API: LLM · Planner uses generative AI for personalized planning output.
- SOP Studio → Gemini API: LLM · SOP workflows use Gemini for drafting, rewriting, and analysis.
- Knowledge Platform → Gemini API: LLM · Knowledge answers are generated with Gemini after retrieval and validation.
- Knowledge Platform → Qdrant: vector search · Semantic retrieval is backed by vector storage.
- Knowledge Platform → Repositories: retrieves · Knowledge workflows can pull persisted knowledge documents and memory state.
- API Router → Knowledge Platform: advisor · AI endpoints expose the knowledge platform to the frontend.
- API Router → AI Planner: planner · Planner endpoints expose scheduling and prioritization features.
- API Router → SOP Studio: sop · SOP endpoints expose drafting and scoring workflows.