How krishna4123/placement_pal works
Purpose and Entry Points
PlacementPal is a full-stack AI placement-preparation system. The React/Vite client starts at client/src/main.tsx and composes routes/UI through client/src/App.tsx. The FastAPI service starts at server/app/main.py, aggregates versioned routers in server/app/api/routes.py, and exposes the two-stage planning pipeline plus vault, plan, and state APIs.
Client Application Shell
The client is a routed session-oriented interface with landing, planner, vault, recall, dashboard, resume, and debug screens. client/src/routes/index.tsx defines navigation and protected areas; client/src/context/SessionContext.tsx carries session identity/state across views. API modules form the frontend/backend boundary, notably client/src/api/pipeline.ts, client/src/api/vault.ts, and client/src/api/plan.ts.
API and Service Boundary
FastAPI handlers validate request/response contracts and delegate domain work. Pipeline execution is exposed from server/app/api/pipeline.py; persistence-facing plan/state endpoints reside in server/app/api/plan.py and server/app/api/state.py. Services encapsulate session lifecycle, generated-plan handling, progress updates, company data, and vault operations: server/app/services/session_service.py, server/app/services/planner_service.py, server/app/services/vault_service.py.
Stateful AI Pipeline
The core control flow is a two-phase LangGraph workflow. Phase 1 accepts a student message, extracts intent/goals, then gathers company intelligence and vault context; Phase 2 turns this accumulated state into active-recall questions and a day-by-day curriculum. Graph state and sequencing are defined in server/app/graph/state_schema.py, server/app/graph/phase1.py, server/app/graph/phase2.py, with execution stages implemented in server/app/graph/nodes.py and transitions in server/app/graph/edges.py.
Agent, Chain, and Tool Layer
CrewAI agents provide specialized roles—message interpretation, company research, knowledge retrieval, recall coaching, and curriculum design—assembled in server/app/agents/crew.py. LangChain chains provide structured LLM transformations for extraction and generation in server/app/chains/extraction_chain.py, server/app/chains/company_chain.py, and server/app/chains/curriculum_chain.py. LLM configuration/factories sit behind server/app/utils/llm.py and server/app/utils/gemini_llm.py; real-time company research calls Tavily through server/app/tools/web_scraper.py.
Knowledge and Persistence
MongoDB, accessed asynchronously through Motor, persists sessions, plans, progress, topics, and related structured state via server/app/database/mongodb.py and server/app/database/collections.py. A local ChromaDB store supports document ingestion and semantic retrieval for RAG in server/app/database/chroma.py; vault APIs and services own PDF/text upload, embedding, and query behavior in server/app/api/vault.py and server/app/services/vault_service.py.
Runtime and External Dependencies
Backend runtime is Python 3.12 with FastAPI/Uvicorn, LangGraph, CrewAI, LangChain, MongoDB, and local ChromaDB; dependencies are declared in server/requirements.txt. Frontend runtime is React 18 under Vite, declared in client/package.json. Required external boundaries are an OpenAI-compatible LLM endpoint, Tavily Search API, and MongoDB; Chroma persists locally under server/chroma_db.
Main entry points: routes.py Versioned API routes · state_schema.py Two-phase LangGraph workflow · planner_service.py Domain services · index.tsx Routes & protected views
Components 19
React Client
- Client entry
client/src/main.tsx - Application shell
client/src/App.tsx - Routes & protected views
client/src/routes/index.tsx - Session context · Carries session identity and state across views.
client/src/context/SessionContext.tsx - Client API modules · Pipeline, vault, and plan requests.
client/src/api/pipeline.ts
FastAPI Service
- FastAPI application
server/app/main.py - Versioned API routes
server/app/api/routes.py - Pipeline API
server/app/api/pipeline.py - Plan & state APIs
server/app/api/plan.py - Vault API
server/app/api/vault.py - Domain services · Session, plan, progress, company, and vault operations.
server/app/services/planner_service.py
AI Planning Pipeline
- Two-phase LangGraph workflow · Phase 1 gathers intent and context; Phase 2 produces recall and curriculum.
server/app/graph/state_schema.py - Workflow stages
server/app/graph/nodes.py - Agents & structured chains · Crew roles and LangChain extraction, research, and curriculum generation.
server/app/agents/crew.py - LLM gateway
server/app/utils/llm.py
Knowledge & Persistence
- MongoDB · Sessions, plans, progress, topics, and state.
server/app/database/mongodb.py - Chroma vault RAG · Local document ingestion, embeddings, and semantic retrieval.
server/app/database/chroma.py
External Services
- OpenAI-compatible LLM
- Tavily Search API
Connections 21
- Client entry → Application shell: mounts
- Application shell → Routes & protected views: composes
- Routes & protected views → Session context: uses
- Routes & protected views → Client API modules: calls
- Client API modules → FastAPI application: HTTP requests
- FastAPI application → Versioned API routes: registers
- Versioned API routes → Pipeline API: routes to
- Versioned API routes → Plan & state APIs: routes to
- Versioned API routes → Vault API: routes to
- Pipeline API → Two-phase LangGraph workflow: executes
- Plan & state APIs → Domain services: delegates
- Vault API → Domain services: delegates
- Two-phase LangGraph workflow → Workflow stages: runs stages
- Workflow stages → Agents & structured chains: invokes
- Agents & structured chains → LLM gateway: generates via
- LLM gateway → OpenAI-compatible LLM: LLM calls
- Agents & structured chains → Tavily Search API: company research
- Two-phase LangGraph workflow → Chroma vault RAG: retrieves vault context
- Domain services → MongoDB: persists state
- Domain services → Chroma vault RAG: ingests and queries
- Two-phase LangGraph workflow → MongoDB: reads and writes plan state