# krishna4123/placement_pal architecture

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

- Interactive diagram: https://gitdiagram.com/krishna4123/placement_pal
- Repository: https://github.com/krishna4123/placement_pal

## Overview

#### 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: [`server/app/api/routes.py`](https://github.com/krishna4123/placement_pal/blob/main/server/app/api/routes.py) (Versioned API routes), [`server/app/graph/state_schema.py`](https://github.com/krishna4123/placement_pal/blob/main/server/app/graph/state_schema.py) (Two-phase LangGraph workflow), [`server/app/services/planner_service.py`](https://github.com/krishna4123/placement_pal/blob/main/server/app/services/planner_service.py) (Domain services), [`client/src/routes/index.tsx`](https://github.com/krishna4123/placement_pal/blob/main/client/src/routes/index.tsx) (Routes & protected views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_client_entry["Client entry<br/>React/Vite bootstrap<br/>[main.tsx]"]
  node_client_app["Application shell<br/>React UI<br/>[App.tsx]"]
  node_client_routes["Routes &amp; protected views<br/>router<br/>[index.tsx]"]
  node_session_context["Session context<br/>client state<br/>[SessionContext.tsx]"]
  node_client_api["Client API modules<br/>HTTP client boundary<br/>[pipeline.ts]"]
end

subgraph group_api["FastAPI Service"]
  node_fastapi_app["FastAPI application<br/>Python service<br/>[main.py]"]
  node_api_routes["Versioned API routes<br/>router aggregation<br/>[routes.py]"]
  node_pipeline_api["Pipeline API<br/>request handlers<br/>[pipeline.py]"]
  node_plan_state_api["Plan &amp; state APIs<br/>request handlers<br/>[plan.py]"]
  node_vault_api["Vault API<br/>request handlers<br/>[vault.py]"]
  node_domain_services["Domain services<br/>service layer<br/>[planner_service.py]"]
end

subgraph group_pipeline["AI Planning Pipeline"]
  node_workflow{{"Two-phase LangGraph workflow<br/>orchestrator<br/>[state_schema.py]"}}
  node_workflow_nodes["Workflow stages<br/>graph nodes<br/>[nodes.py]"]
  node_agents_chains["Agents &amp; structured chains<br/>AI task layer<br/>[crew.py]"]
  node_llm_gateway["LLM gateway<br/>LLM factory<br/>[llm.py]"]
end

subgraph group_data["Knowledge &amp; Persistence"]
  node_mongo[("MongoDB<br/>structured persistence<br/>[mongodb.py]")]
  node_vault_rag[("Chroma vault RAG<br/>vector store<br/>[chroma.py]")]
end

subgraph group_external["External Services"]
  node_llm_endpoint(("OpenAI-compatible LLM<br/>external AI endpoint"))
  node_tavily(("Tavily Search API<br/>web research"))
end

node_client_entry -->|"mounts"| node_client_app
node_client_app -->|"composes"| node_client_routes
node_client_routes -->|"uses"| node_session_context
node_client_routes -->|"calls"| node_client_api
node_client_api -->|"HTTP requests"| node_fastapi_app
node_fastapi_app -->|"registers"| node_api_routes
node_api_routes -->|"routes to"| node_pipeline_api
node_api_routes -->|"routes to"| node_plan_state_api
node_api_routes -->|"routes to"| node_vault_api
node_pipeline_api -->|"executes"| node_workflow
node_plan_state_api -->|"delegates"| node_domain_services
node_vault_api -->|"delegates"| node_domain_services
node_workflow -->|"runs stages"| node_workflow_nodes
node_workflow_nodes -->|"invokes"| node_agents_chains
node_agents_chains -->|"generates via"| node_llm_gateway
node_llm_gateway -->|"LLM calls"| node_llm_endpoint
node_agents_chains -->|"company research"| node_tavily
node_workflow -->|"retrieves vault context"| node_vault_rag
node_domain_services -->|"persists state"| node_mongo
node_domain_services -->|"ingests and queries"| node_vault_rag
node_workflow -->|"reads and writes plan state"| node_mongo

click node_client_entry "https://github.com/krishna4123/placement_pal/blob/main/client/src/main.tsx"
click node_client_app "https://github.com/krishna4123/placement_pal/blob/main/client/src/App.tsx"
click node_client_routes "https://github.com/krishna4123/placement_pal/blob/main/client/src/routes/index.tsx"
click node_session_context "https://github.com/krishna4123/placement_pal/blob/main/client/src/context/SessionContext.tsx"
click node_client_api "https://github.com/krishna4123/placement_pal/blob/main/client/src/api/pipeline.ts"
click node_fastapi_app "https://github.com/krishna4123/placement_pal/blob/main/server/app/main.py"
click node_api_routes "https://github.com/krishna4123/placement_pal/blob/main/server/app/api/routes.py"
click node_pipeline_api "https://github.com/krishna4123/placement_pal/blob/main/server/app/api/pipeline.py"
click node_plan_state_api "https://github.com/krishna4123/placement_pal/blob/main/server/app/api/plan.py"
click node_vault_api "https://github.com/krishna4123/placement_pal/blob/main/server/app/api/vault.py"
click node_domain_services "https://github.com/krishna4123/placement_pal/blob/main/server/app/services/planner_service.py"
click node_workflow "https://github.com/krishna4123/placement_pal/blob/main/server/app/graph/state_schema.py"
click node_workflow_nodes "https://github.com/krishna4123/placement_pal/blob/main/server/app/graph/nodes.py"
click node_agents_chains "https://github.com/krishna4123/placement_pal/blob/main/server/app/agents/crew.py"
click node_llm_gateway "https://github.com/krishna4123/placement_pal/blob/main/server/app/utils/llm.py"
click node_mongo "https://github.com/krishna4123/placement_pal/blob/main/server/app/database/mongodb.py"
click node_vault_rag "https://github.com/krishna4123/placement_pal/blob/main/server/app/database/chroma.py"

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_client_entry,node_client_app,node_client_routes,node_session_context,node_client_api toneBlue
class node_fastapi_app,node_api_routes,node_pipeline_api,node_plan_state_api,node_vault_api,node_domain_services toneAmber
class node_workflow,node_workflow_nodes,node_agents_chains,node_llm_gateway toneMint
class node_mongo,node_vault_rag toneRose
class node_llm_endpoint,node_tavily toneIndigo
```

## Components

### React Client

- [Client entry](https://github.com/krishna4123/placement_pal/blob/main/client/src/main.tsx): React/Vite bootstrap · `client/src/main.tsx`
- [Application shell](https://github.com/krishna4123/placement_pal/blob/main/client/src/App.tsx): React UI · `client/src/App.tsx`
- [Routes & protected views](https://github.com/krishna4123/placement_pal/blob/main/client/src/routes/index.tsx): router · `client/src/routes/index.tsx`
- [Session context](https://github.com/krishna4123/placement_pal/blob/main/client/src/context/SessionContext.tsx): client state · Carries session identity and state across views. · `client/src/context/SessionContext.tsx`
- [Client API modules](https://github.com/krishna4123/placement_pal/blob/main/client/src/api/pipeline.ts): HTTP client boundary · Pipeline, vault, and plan requests. · `client/src/api/pipeline.ts`

### FastAPI Service

- [FastAPI application](https://github.com/krishna4123/placement_pal/blob/main/server/app/main.py): Python service · `server/app/main.py`
- [Versioned API routes](https://github.com/krishna4123/placement_pal/blob/main/server/app/api/routes.py): router aggregation · `server/app/api/routes.py`
- [Pipeline API](https://github.com/krishna4123/placement_pal/blob/main/server/app/api/pipeline.py): request handlers · `server/app/api/pipeline.py`
- [Plan & state APIs](https://github.com/krishna4123/placement_pal/blob/main/server/app/api/plan.py): request handlers · `server/app/api/plan.py`
- [Vault API](https://github.com/krishna4123/placement_pal/blob/main/server/app/api/vault.py): request handlers · `server/app/api/vault.py`
- [Domain services](https://github.com/krishna4123/placement_pal/blob/main/server/app/services/planner_service.py): service layer · Session, plan, progress, company, and vault operations. · `server/app/services/planner_service.py`

### AI Planning Pipeline

- [Two-phase LangGraph workflow](https://github.com/krishna4123/placement_pal/blob/main/server/app/graph/state_schema.py): orchestrator · Phase 1 gathers intent and context; Phase 2 produces recall and curriculum. · `server/app/graph/state_schema.py`
- [Workflow stages](https://github.com/krishna4123/placement_pal/blob/main/server/app/graph/nodes.py): graph nodes · `server/app/graph/nodes.py`
- [Agents & structured chains](https://github.com/krishna4123/placement_pal/blob/main/server/app/agents/crew.py): AI task layer · Crew roles and LangChain extraction, research, and curriculum generation. · `server/app/agents/crew.py`
- [LLM gateway](https://github.com/krishna4123/placement_pal/blob/main/server/app/utils/llm.py): LLM factory · `server/app/utils/llm.py`

### Knowledge & Persistence

- [MongoDB](https://github.com/krishna4123/placement_pal/blob/main/server/app/database/mongodb.py): structured persistence · Sessions, plans, progress, topics, and state. · `server/app/database/mongodb.py`
- [Chroma vault RAG](https://github.com/krishna4123/placement_pal/blob/main/server/app/database/chroma.py): vector store · Local document ingestion, embeddings, and semantic retrieval. · `server/app/database/chroma.py`

### External Services

- **OpenAI-compatible LLM**: external AI endpoint
- **Tavily Search API**: web research

## Connections

- 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