# mahamudul-hasan-cse/gradpilot-ai architecture

> Architecture diagram of the GitHub repository mahamudul-hasan-cse/gradpilot-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahamudul-hasan-cse/gradpilot-ai
- Repository: https://github.com/mahamudul-hasan-cse/gradpilot-ai

## Overview

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: [`apps/api/app/repositories`](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/repositories) (Repositories), [`apps/api/app/api/v1`](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/api/v1) (API Router), [`apps/web/src/app`](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/web/src/app) (App Router), [`apps/api/app/services/knowledge`](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/knowledge) (Knowledge Platform)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
end

subgraph group_backend["Backend API"]
  node_api_router["API Router<br/>FastAPI routes"]
  node_api_services["Domain Services<br/>service layer"]
  node_api_repos["Repositories<br/>db access"]
  node_api_models[("Data Models<br/>SQLAlchemy models")]
  node_api_schemas["API Schemas<br/>Pydantic schemas"]
  node_ingestion_pipeline{{"Ingestion Pipeline<br/>extract/validate/load"}}
  node_knowledge_platform{{"Knowledge Platform<br/>RAG pipeline"}}
  node_profile_intel["Profile Intelligence<br/>analysis engine"]
  node_rec_engine["Recommendations<br/>ranking engine"]
  node_scholarship_match["Scholarship Matching<br/>match engine"]
  node_university_discovery["University Discovery<br/>catalog service"]
  node_application_workspace["Application Workspace<br/>workflow service"]
  node_digital_twin["Digital Twin<br/>state aggregator"]
  node_ai_planner["AI Planner<br/>planning engine"]
  node_sop_studio["SOP Studio<br/>writing engine"]
end

subgraph group_frontend["Frontend App"]
  node_web_app_router["App Router<br/>Next.js routes"]
  node_web_ui_shell["UI Shell<br/>React components"]
  node_web_state["Client State<br/>Query + store"]
  node_web_auth["NextAuth<br/>auth integration<br/>[route.ts]"]
end

subgraph group_shared["Shared Package"]
  node_shared_pkg["Shared Types<br/>TS package<br/>[index.ts]"]
end

subgraph group_external["External Systems"]
  node_gemini(("Gemini API<br/>external LLM"))
  node_postgres[("PostgreSQL<br/>database")]
  node_qdrant[("Qdrant<br/>vector store")]
end

node_web_app_router -->|"renders"| node_web_ui_shell
node_web_app_router -->|"fetches"| node_web_state
node_web_auth -->|"sessions"| node_web_state
node_web_app_router -->|"HTTP /api/v1"| node_api_router
node_web_app_router -->|"types"| node_shared_pkg
node_api_router -->|"contracts"| node_api_schemas
node_api_router -->|"delegates"| node_api_services
node_api_services -->|"persists"| node_api_repos
node_api_repos -->|"maps"| node_api_models
node_api_models -->|"stores"| node_postgres
node_ingestion_pipeline -->|"loads"| node_api_models
node_ingestion_pipeline -->|"syncs"| node_postgres
node_profile_intel -->|"reads"| node_api_repos
node_profile_intel -->|"feeds"| node_rec_engine
node_rec_engine -.->|"parallelizes"| node_scholarship_match
node_rec_engine -->|"scores"| node_api_repos
node_university_discovery -.->|"catalog source"| node_ingestion_pipeline
node_university_discovery -->|"queries"| node_api_repos
node_scholarship_match -->|"queries"| node_api_repos
node_application_workspace -->|"tracks"| node_api_repos
node_application_workspace -->|"syncs"| node_digital_twin
node_digital_twin -->|"aggregates"| node_api_repos
node_ai_planner -->|"consumes"| node_digital_twin
node_ai_planner -->|"LLM"| node_gemini
node_sop_studio -->|"LLM"| node_gemini
node_knowledge_platform -->|"LLM"| node_gemini
node_knowledge_platform -->|"vector search"| node_qdrant
node_knowledge_platform -->|"retrieves"| node_api_repos
node_api_router -->|"advisor"| node_knowledge_platform
node_api_router -->|"planner"| node_ai_planner
node_api_router -->|"sop"| node_sop_studio

click node_web_app_router "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/web/src/app"
click node_web_ui_shell "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/web/src/components"
click node_web_state "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/web/src/lib"
click node_web_auth "https://github.com/mahamudul-hasan-cse/gradpilot-ai/blob/main/apps/web/src/app/api/auth/[...nextauth]/route.ts"
click node_api_router "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/api/v1"
click node_api_services "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services"
click node_api_repos "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/repositories"
click node_api_models "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/models"
click node_api_schemas "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/schemas"
click node_ingestion_pipeline "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/ingestion"
click node_knowledge_platform "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/knowledge"
click node_profile_intel "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/profile_intelligence"
click node_rec_engine "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/recommendation"
click node_scholarship_match "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/scholarship_recommendation"
click node_university_discovery "https://github.com/mahamudul-hasan-cse/gradpilot-ai/blob/main/apps/api/app/services/university_discovery.py"
click node_application_workspace "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/application_workspace"
click node_digital_twin "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/digital_twin"
click node_ai_planner "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/ai_planner"
click node_sop_studio "https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/sop_studio"
click node_shared_pkg "https://github.com/mahamudul-hasan-cse/gradpilot-ai/blob/main/packages/shared/src/index.ts"

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_api_router,node_api_services,node_api_repos,node_api_models,node_api_schemas,node_ingestion_pipeline,node_knowledge_platform,node_profile_intel,node_rec_engine,node_scholarship_match,node_university_discovery,node_application_workspace,node_digital_twin,node_ai_planner,node_sop_studio toneAmber
class node_web_app_router,node_web_ui_shell,node_web_state,node_web_auth toneMint
class node_shared_pkg toneRose
class node_gemini,node_postgres,node_qdrant toneIndigo
```

## Components

### Backend API

FastAPI service with domain logic, persistence, AI orchestration, and ingestion.

- [API Router](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/api/v1): FastAPI routes · Versioned HTTP endpoints for auth, profile, discovery, universities, scholarships, documents, planner, AI, and applications. · `apps/api/app/api/v1`
- [Domain Services](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services): service layer · Backend business logic for profiles, recommendations, scholarships, universities, applications, AI, SOPs, and student workflows. · `apps/api/app/services`
- [Repositories](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/repositories): db access · Persistence isolation layer for the backend domain models and workspace subdomains. · `apps/api/app/repositories`
- [Data Models](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/models): SQLAlchemy models · Persistent entities for students, universities, scholarships, applications, documents, knowledge, digital twin, planner, and SOP data. · `apps/api/app/models`
- [API Schemas](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/schemas): Pydantic schemas · Request and response contracts shared across backend endpoints and service boundaries. · `apps/api/app/schemas`
- [Ingestion Pipeline](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/ingestion): extract/validate/load · Pipeline for scraping, extracting, normalizing, deduplicating, and validating source data and uploads. · `apps/api/app/ingestion`
- [Knowledge Platform](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/knowledge): RAG pipeline · 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](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/profile_intelligence): analysis engine · Computes readiness, recommendations, and derived profile insights used by discovery, dashboard, and planner features. · `apps/api/app/services/profile_intelligence`
- [Recommendations](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/recommendation): ranking engine · General recommendation and explainer logic for ranked matches and dashboard widgets. · `apps/api/app/services/recommendation`
- [Scholarship Matching](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/scholarship_recommendation): match engine · Scholarship-specific scoring and explanation path built on profile and catalog data. · `apps/api/app/services/scholarship_recommendation`
- [University Discovery](https://github.com/mahamudul-hasan-cse/gradpilot-ai/blob/main/apps/api/app/services/university_discovery.py): catalog service · Read-heavy discovery, filtering, and ranking flows for university catalog data. · `apps/api/app/services/university_discovery.py`
- [Application Workspace](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/application_workspace): workflow service · Application progress, tasks, deadlines, notes, documents, analytics, and activity tracking. · `apps/api/app/services/application_workspace`
- [Digital Twin](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/digital_twin): state aggregator · Continuously updated student representation combining profile, document, and event data. · `apps/api/app/services/digital_twin`
- [AI Planner](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/ai_planner): planning engine · Generates personalized timelines, reminders, and task prioritization from profile and application context. · `apps/api/app/services/ai_planner`
- [SOP Studio](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/api/app/services/sop_studio): writing engine · 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](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/web/src/app): Next.js routes · Frontend pages and route handlers for dashboard, profile, discovery, applications, admin, auth, and settings. · `apps/web/src/app`
- [UI Shell](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/web/src/components): React components · Shared layout, dashboard widgets, and UI primitives that frame the frontend experience. · `apps/web/src/components`
- [Client State](https://github.com/mahamudul-hasan-cse/gradpilot-ai/tree/main/apps/web/src/lib): Query + store · Frontend data-fetching and local state management via React Query, Zustand, and auth hooks. · `apps/web/src/lib`
- [NextAuth](https://github.com/mahamudul-hasan-cse/gradpilot-ai/blob/main/apps/web/src/app/api/auth/[...nextauth]/route.ts): auth integration · 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](https://github.com/mahamudul-hasan-cse/gradpilot-ai/blob/main/packages/shared/src/index.ts): TS package · 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**: external LLM · Primary generative AI dependency for advisor, rewriting, summarization, planning, and SOP features.
- **PostgreSQL**: database · System of record for users, profiles, universities, scholarships, applications, documents, and AI feature state.
- **Qdrant**: vector store · Vector retrieval storage used by semantic search in the knowledge platform.

## Connections

- 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.
