TalentNest Job Portal

A production-ready, AI-powered job portal connecting job seekers with employers. Built with FastAPI, Next.js 14, MongoDB Atlas, ChromaDB, LangChain, and OpenAI GPT-4o (with Anthropic Claude fallback). Fully containerized with Docker and docker-compose. Features include AI-powered job recommendations, intelligent candidate matching, RAG-based career assistant, resume parsing, interview scheduling, rate limiting, dark mode, and n8n workflow automation.

👥 Development Team

Course: AI Vibe Coding | Fall 2025
Offered by: Arizona State University (https://www.asu.edu)
Taught through: Revature (https://www.revature.com)

Project: Greenfield | Job Portal
Timeline: 2 Weeks | Team: 5 Developers
Branch Strategy (GitHub): Feature branches → dev → main
Company/Product name chosen by Contributors: TalentNest

Project Contributors (Alphabetical Order):

Darimar C.
Erica H.
Jason M.
Keith S.
Safa M.

📊 Project Status

Current Phase: ✅ ALL PHASES COMPLETE - PRODUCTION READY 🚀

Version: 2.0.0 | Status: Production Ready | Completion: 100%

✅ All Features Implemented

Phase 1: Foundation ✅ COMPLETE

✅ FastAPI backend with async/await
✅ Next.js 14 frontend with App Router
✅ MongoDB Atlas integration with Beanie ODM
✅ JWT authentication (register, login, logout)
✅ Role-based access control (Job Seeker / Employer)
✅ Docker containerization with docker-compose
✅ Comprehensive documentation with Mermaid diagrams

Phase 2: Core Features ✅ COMPLETE

✅ Job seeker profile management
✅ Resume upload and AI parsing (PDF/DOCX)
✅ Job search with filters (location, type, experience)
✅ Job application system with cover letters
✅ Employer job posting (CRUD operations)
✅ Application review and management
✅ Email notification system (SMTP)
✅ Application status tracking

Phase 3: AI Features ✅ COMPLETE

✅ AI job recommendations - ChromaDB vector embeddings + AI scoring (70% vector + 30% AI)
✅ AI candidate matching - ChromaDB vector embeddings + AI scoring (70% vector + 30% AI)
✅ AI cover letter generation - GPT-4o with provider fallback
✅ RAG-based AI career assistant - Context-aware chatbot
✅ Resume parsing - AI-powered skill extraction
✅ Interview scheduling - Complete calendar system with email notifications
✅ LangChain integration - Structured AI workflows with prompt chains
✅ n8n workflow automation - Optional AI orchestration backend

Phase 4: Polish & Deployment ✅ COMPLETE

✅ Dark mode - Full theme system with system preference detection
✅ Responsive design - Mobile-first with Tailwind CSS
✅ Rate limiting - Configurable protection on all critical endpoints
✅ Comprehensive testing - Manual tests with GUI testing tracker tool (test_tracker.py)
✅ Architecture diagrams - ERD, System Architecture, Frontend Architecture, Flow diagrams (Mermaid)
✅ Production optimization - Docker multi-stage builds, health checks, logging
✅ Error handling - Comprehensive validation and user-friendly error messages
✅ Security hardening - CORS, JWT, bcrypt, input validation

🎁 Bonus Features (Beyond Specification)

✅ AI Provider Abstraction - Automatic fallback between OpenAI and Anthropic Claude
✅ Configurable Logging - Separate control for app logs vs HTTP logs
✅ Colored Console Output - Enhanced developer experience with visual feedback
✅ Password Visibility Toggle - Enhanced security UX with eye icon
✅ Enhanced Navigation - Clear "Employer Dashboard" labeling
✅ Independent GUI Testing Tool - Standalone test_tracker.py application for manual test tracking with progress saving, team collaboration, and comprehensive test coverage
✅ Database Seeding Tools - Comprehensive content generation for testing
✅ Configurable Server Settings - HOST and PORT environment variables
✅ ChromaDB Vector Store - Semantic search with text-embedding-3-small
✅ LangChain Chains - Recommendation and candidate matching chains
✅ n8n Integration - Optional workflow automation for AI orchestration

🏗️ System Architecture

📌 Note: The diagrams below are best viewed on GitHub or using a Mermaid-compatible viewer. In your IDE, you can zoom in on the preview or view the raw Mermaid code for details.

System Flow Diagram

graph LR
    %% Client Layer
    Client[👤 Web Browser]
    
    %% Frontend Layer
    Frontend["⚛️ Next.js 14 Frontend<br/>- App Router<br/>- TypeScript<br/>- Tailwind CSS<br/>- Dark Mode"]
    
    %% API Gateway with Rate Limiting
    RateLimit["⚡ Rate Limiter<br/>slowapi<br/>Configurable Limits"]
    API["🚀 FastAPI Backend<br/>- REST API<br/>- JWT Auth<br/>- Async/Await"]
    
    %% Service Layer
    AuthSvc["🔐 Auth Service<br/>JWT + Bcrypt"]
    JobSvc["💼 Job Service<br/>CRUD + Search"]
    AppSvc["📋 Application Service<br/>Status Management"]
    ResumeSvc["📄 Resume Service<br/>AI Parsing"]
    EmailSvc["📧 Email Service<br/>SMTP"]
    
    %% AI Layer with Provider Abstraction
    AIProvider["🤖 AI Provider Layer<br/>- Provider Factory<br/>- Auto Fallback"]
    AISvc["🎯 AI Services<br/>- Cover Letters<br/>- Recommendations<br/>- RAG Assistant<br/>- ChromaDB Vector Store<br/>- LangChain Chains"]
    
    %% Data Layer
    DB[("🗄️ MongoDB Atlas<br/>- Users<br/>- Jobs<br/>- Applications<br/>- Resumes")]
    VectorDB[("🔍 ChromaDB<br/>- Job Embeddings<br/>- Profile Embeddings")]
    
    %% External Services
    OpenAI["🧠 OpenAI GPT-4o<br/>Primary Provider"]
    Anthropic["🤖 Anthropic Claude<br/>Fallback Provider"]
    SMTP["📮 SMTP Server"]
    Storage["💾 File Storage"]
    n8n["🔗 n8n Workflows<br/>Optional Automation"]
    
    %% Main Flow with Rate Limiting
    Client ==>|"HTTP Requests"| Frontend
    Frontend ==>|"REST API + JWT"| RateLimit
    RateLimit ==>|"Rate Check Pass"| API
    RateLimit -.->|"429 Too Many Requests"| Frontend
    
    %% API to Services
    API ==> AuthSvc
    API ==> JobSvc
    API ==> AppSvc
    API ==> ResumeSvc
    API ==> AISvc
    
    %% Services to Data
    AuthSvc ==> DB
    JobSvc ==> DB
    AppSvc ==> DB
    ResumeSvc ==> DB
    
    %% Services to AI with Provider Layer
    ResumeSvc ==> AISvc
    JobSvc ==> AISvc
    AISvc ==> AIProvider
    AISvc ==> VectorDB
    
    %% AI Provider Fallback Logic
    AIProvider ==>|"Primary"| OpenAI
    AIProvider -.->|"Fallback on Error"| Anthropic
    
    %% Optional n8n Integration
    AISvc -.->|"Optional"| n8n
    
    %% Email Flow
    AppSvc -.->|"Async Trigger"| EmailSvc
    EmailSvc ==> SMTP
    
    %% File Storage
    ResumeSvc ==> Storage
    
    %% Styling
    classDef frontend fill:#61dafb,stroke:#333,stroke-width:3px,color:#000
    classDef backend fill:#009688,stroke:#333,stroke-width:3px,color:#fff
    classDef ratelimit fill:#f44336,stroke:#333,stroke-width:3px,color:#fff
    classDef service fill:#4caf50,stroke:#333,stroke-width:3px,color:#fff
    classDef ai fill:#ff9800,stroke:#333,stroke-width:3px,color:#fff
    classDef data fill:#2196f3,stroke:#333,stroke-width:3px,color:#fff
    classDef external fill:#9c27b0,stroke:#333,stroke-width:3px,color:#fff
    
    class Client,Frontend frontend
    class RateLimit ratelimit
    class API backend
    class AuthSvc,JobSvc,AppSvc,ResumeSvc,EmailSvc service
    class AISvc,AIProvider ai
    class DB,VectorDB data
    class OpenAI,Anthropic,SMTP,Storage,n8n external
    
    %% Link styling for better visibility
    linkStyle default stroke:#666,stroke-width:2px

Simplified Architecture Overview:

Client → Makes HTTP requests to frontend
Frontend (Next.js) → Sends REST API calls with JWT to backend
Backend (FastAPI) → Routes requests to appropriate services
Services Layer → Handles business logic (Auth, Jobs, Applications, Resume, Email)
AI Services → Processes AI features (GPT-4o integration)
Database → MongoDB Atlas stores all application data
External Services → OpenAI API, SMTP server, File storage

Detailed System Architecture Diagram

For a more detailed view, here's the complete architecture broken down by layers:

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#ffffff','primaryTextColor':'#000000','primaryBorderColor':'#000000','lineColor':'#333333','secondaryColor':'#f4f4f4','tertiaryColor':'#ffffff','clusterBkg':'#f9f9f9','clusterBorder':'#333333','titleColor':'#000000','edgeLabelBackground':'#ffffff'}}}%%
graph TB
    subgraph Client["<b>👥 CLIENT LAYER</b>"]
        Browser["🌐 Web Browser<br/>Desktop"]
        Mobile["📱 Mobile Browser<br/>Responsive"]
    end
    
    subgraph Frontend["<b>⚛️ FRONTEND LAYER - Next.js 14</b>"]
        Pages["📄 Pages<br/>Public & Protected Routes"]
        Components["🧩 Components<br/>UI & Features<br/>Dark Mode Support"]
        Store["💾 State Management<br/>Zustand<br/>Auth & User State"]
        APIClient["🔌 API Client<br/>Axios + JWT<br/>429 Error Handling"]
    end
    
    subgraph Security["<b>🛡️ SECURITY & RATE LIMITING</b>"]
        RateLimit["⚡ Rate Limiter<br/>slowapi<br/>Auth: 5/min<br/>Jobs: 10/min<br/>Apps: 20/min<br/>AI: 30/min"]
        JWT["🔐 JWT Auth<br/>Token Validation<br/>Role-Based Access"]
    end
    
    subgraph Backend["<b>🚀 BACKEND LAYER - FastAPI</b>"]
        Routes["🛣️ API Routes<br/>/api/v1/*<br/>Async Endpoints"]
        Services["⚙️ Business Services<br/>Auth, Jobs, Apps,<br/>Resume, Email"]
        AIServices["🎯 AI Services<br/>Recommendations<br/>Candidate Matching<br/>RAG Assistant<br/>Cover Letters"]
    end
    
    subgraph AILayer["<b>🤖 AI ORCHESTRATION LAYER</b>"]
        AIProvider["🔄 AI Provider Factory<br/>Auto Fallback Logic"]
        LangChain["⛓️ LangChain<br/>Recommendation Chain<br/>Matching Chain"]
        VectorStore["🔍 ChromaDB<br/>Vector Embeddings<br/>Semantic Search"]
    end
    
    subgraph Data["<b>🗄️ DATA LAYER</b>"]
        MongoDB[("💾 MongoDB Atlas<br/>Collections:<br/>Users, Jobs,<br/>Applications,<br/>Resumes, Interviews,<br/>Conversations")]
        ChromaDB[("🔍 ChromaDB<br/>Vector Store:<br/>Job Embeddings<br/>Profile Embeddings")]
    end
    
    subgraph External["<b>🌐 EXTERNAL SERVICES</b>"]
        OpenAI["🧠 OpenAI GPT-4o<br/>text-embedding-3-small<br/>Primary Provider"]
        Anthropic["🤖 Anthropic Claude<br/>Fallback Provider"]
        SMTP["📮 SMTP Email<br/>Notifications"]
        Files["💾 File Storage<br/>Resume PDFs"]
        n8n["🔗 n8n Workflows<br/>Optional Automation"]
    end
    
    %% Connections - Client to Frontend
    Browser ==> Pages
    Mobile ==> Pages
    Pages ==> Components
    Components ==> Store
    Store ==> APIClient
    
    %% Frontend to Security Layer
    APIClient ==>|REST + JWT| RateLimit
    RateLimit ==>|Rate Check| JWT
    RateLimit -.->|429 Error| APIClient
    
    %% Security to Backend
    JWT ==>|Validated| Routes
    Routes ==> Services
    Routes ==> AIServices
    
    %% Services to Data
    Services ==> MongoDB
    
    %% AI Services to AI Layer
    AIServices ==> AIProvider
    AIServices ==> LangChain
    AIServices ==> VectorStore
    
    %% AI Layer to External
    AIProvider ==>|Primary| OpenAI
    AIProvider -.->|Fallback| Anthropic
    LangChain ==> AIProvider
    VectorStore ==> ChromaDB
    
    %% Optional n8n Integration
    AIServices -.->|Optional| n8n
    
    %% Services to External
    Services ==> SMTP
    Services ==> Files
    
    %% Styling
    classDef clientStyle fill:#e3f2fd,stroke:#1976d2,stroke-width:3px
    classDef frontendStyle fill:#e8f5e9,stroke:#388e3c,stroke-width:3px
    classDef securityStyle fill:#ffebee,stroke:#c62828,stroke-width:3px
    classDef backendStyle fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    classDef aiStyle fill:#fff9c4,stroke:#f57f17,stroke-width:3px
    classDef dataStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px
    classDef externalStyle fill:#fce4ec,stroke:#c2185b,stroke-width:3px
    
    class Client clientStyle
    class Frontend frontendStyle
    class Security securityStyle
    class Backend backendStyle
    class AILayer aiStyle
    class Data dataStyle
    class External externalStyle
    
    %% Link styling for better visibility
    linkStyle default stroke:#666,stroke-width:2px

Key Architectural Highlights

🎯 Separation of Concerns

Frontend (Next.js 14): Handles UI/UX, client-side routing, state management, and dark mode theming
Backend (FastAPI): Manages business logic, data validation, API endpoints, and rate limiting
Security Layer: Dedicated rate limiting and JWT authentication middleware
AI Orchestration Layer: Isolated AI provider abstraction with automatic fallback
Database (MongoDB + ChromaDB): Dual database architecture for structured data and vector embeddings
AI Services: Separated services for resume parsing, recommendations, candidate matching, and RAG assistant

🔐 Security Architecture

JWT Authentication: Stateless authentication with Bearer tokens and httpOnly cookies
Password Hashing: Bcrypt with salt rounds for secure password storage
Role-Based Access Control (RBAC): Separate permissions for Job Seekers and Employers
Rate Limiting: slowapi integration with configurable limits per endpoint (Auth: 5/min, Jobs: 10/min, Apps: 20/min, AI: 30/min)
CORS Configuration: Controlled cross-origin resource sharing with whitelist
Environment Variables: Sensitive credentials isolated in .env files
Input Validation: Pydantic models for comprehensive request/response validation

🚀 Performance Optimizations

Async/Await: FastAPI uses async operations for non-blocking I/O
Connection Pooling: MongoDB connection pooling for efficient database access
Next.js App Router: Automatic code splitting and optimized loading
Docker Multi-Stage Builds: Minimal production image sizes with layer caching
Vector Search: ChromaDB for fast semantic similarity search (70% vector + 30% AI scoring)
Caching: API client caching for repeated requests
Background Tasks: Email and AI processing run asynchronously

🤖 AI Integration & Orchestration

AI Provider Abstraction: Factory pattern with automatic fallback between OpenAI and Anthropic Claude
OpenAI GPT-4o: Primary provider for resume parsing, cover letter generation, and recommendations
Anthropic Claude: Automatic fallback provider for resilience
ChromaDB Vector Store: Semantic search with OpenAI text-embedding-3-small embeddings
LangChain Integration: Structured AI workflows with recommendation and candidate matching chains
RAG Pipeline: Retrieval-Augmented Generation for context-aware AI career assistant
n8n Workflow Automation: Optional AI orchestration backend for complex workflows
Graceful Degradation: AI features optional; app works without AI providers
Blended Scoring: 70% vector similarity + 30% AI scoring for optimal matching accuracy

📧 Communication Layer

SMTP Email Service: Automated notifications for application events and interview scheduling
HTML Email Templates: Professional, responsive email designs
Background Tasks: Email sending happens asynchronously via FastAPI background tasks
Error Handling: Graceful fallback if email service unavailable
Event-Driven: Triggered on application status changes, interview scheduling, and shortlisting

📊 Enhanced Data Flow

User Action → Frontend captures input with validation
API Request → Axios sends HTTP request with JWT token
Rate Limiting → slowapi checks request rate limits (429 if exceeded)
JWT Validation → Token verified and user role extracted
Backend Processing → FastAPI validates, processes, and applies business logic
Database Operation → MongoDB stores/retrieves data via Beanie ODM
Vector Search (if needed) → ChromaDB performs semantic similarity search
AI Processing (if needed) → AI Provider Layer calls OpenAI (or Anthropic fallback)
Response → Backend returns structured JSON response
UI Update → Frontend updates state and re-renders components with dark mode support

🔄 State Management

Zustand Store: Lightweight global state for authentication and user data
React Hook Form: Local form state with validation
Theme Context: Dark mode state with localStorage persistence and system preference detection
Server State: API responses cached and managed by React Query patterns
LocalStorage: Persistent JWT token and theme preference storage

🐳 Containerization & Deployment

Docker Compose: Multi-container orchestration for backend, frontend, and optional MongoDB
Multi-Stage Builds: Optimized Docker images with minimal production footprint
Health Checks: Container health monitoring for automatic restarts
Environment Configuration: Centralized .env management with validation
Production Ready: Configured for cloud deployment (AWS, GCP, Azure)

🎨 Frontend Architecture

Frontend Flow Diagram

graph LR
    %% App Router
    Router["📱 Next.js App Router<br/>File-based Routing"]
    
    %% Pages Layer
    Pages["📄 Pages Layer<br/>- Public Routes<br/>- Job Seeker Routes<br/>- Employer Routes"]
    
    %% Components Layer
    Components["🧩 Components<br/>- Layout (Navbar, Footer)<br/>- UI (Button, Input, Card)<br/>- Features (Forms, Cards)"]
    
    %% State Management
    State["💾 State Management<br/>Zustand Store<br/>- Auth State<br/>- User Data<br/>- Theme Context<br/>- Dark Mode"]
    
    %% API Client
    API["🔌 API Client<br/>Axios + JWT<br/>- Auth API<br/>- Jobs API<br/>- Applications API<br/>- 429 Error Handling"]
    
    %% Utilities
    Utils["🛠️ Utilities<br/>- Hooks<br/>- Types<br/>- Helpers"]
    
    %% Backend Connection
    Backend["🚀 Backend API<br/>FastAPI"]
    
    %% Flow
    Router ==>|"Route to"| Pages
    Pages ==>|"Use"| Components
    Components ==>|"Read/Write"| State
    Components ==>|"Call"| API
    Components ==>|"Import"| Utils
    State ==>|"Persist Token"| API
    API ==>|"HTTP + JWT"| Backend
    
    %% Styling
    classDef router fill:#61dafb,stroke:#333,stroke-width:3px,color:#000
    classDef pages fill:#4ecdc4,stroke:#333,stroke-width:3px,color:#000
    classDef components fill:#95e1d3,stroke:#333,stroke-width:3px,color:#000
    classDef state fill:#764abc,stroke:#333,stroke-width:3px,color:#fff
    classDef api fill:#ff6b6b,stroke:#333,stroke-width:3px,color:#fff
    classDef utils fill:#ffd93d,stroke:#333,stroke-width:3px,color:#000
    classDef backend fill:#009688,stroke:#333,stroke-width:3px,color:#fff
    
    class Router router
    class Pages pages
    class Components components
    class State state
    class API api
    class Utils utils
    class Backend backend
    
    %% Link styling
    linkStyle default stroke:#333,stroke-width:3px

Frontend Architecture Overview:

App Router → File-based routing system manages all pages
Pages Layer → Public, Job Seeker, and Employer routes
Components → Reusable UI and feature components with dark mode support
State Management → Zustand store for auth, Theme Context for dark mode
API Client → Axios instance with JWT and 429 rate limit error handling
Utilities → Hooks, types, and helper functions
Backend → FastAPI REST API integration with rate limiting

Detailed Frontend Architecture Diagram

For a comprehensive view of all frontend components and their relationships:

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#ffffff','primaryTextColor':'#000000','primaryBorderColor':'#000000','lineColor':'#333333','secondaryColor':'#f4f4f4','tertiaryColor':'#ffffff','clusterBkg':'#f9f9f9','clusterBorder':'#333333','titleColor':'#000000','edgeLabelBackground':'#ffffff'}}}%%
graph TB
    subgraph Routes["<b>📱 ROUTES - Next.js 14 App Router</b>"]
        PublicRoutes["🌐 Public Routes<br/>Home, Jobs, Login, Register"]
        JSRoutes["👤 Job Seeker Routes<br/>Dashboard, Profile, Applications"]
        EMPRoutes["💼 Employer Routes<br/>Dashboard, Post Jobs, Review Apps"]
    end
    
    subgraph Components["<b>🧩 COMPONENTS LAYER</b>"]
        Layout["📐 Layout<br/>Navbar, Footer, DashboardLayout"]
        UI["🎨 UI Components<br/>Button, Input, Card, Modal"]
        Features["⭐ Feature Components<br/>Forms, Cards, Filters"]
    end
    
    subgraph State["<b>💾 STATE MANAGEMENT</b>"]
        AuthStore["🔐 Zustand Auth Store<br/>user, token, isAuthenticated<br/>login(), logout(), setUser()"]
        ThemeContext["🎨 Theme Context<br/>theme, toggleTheme()<br/>Dark Mode State<br/>System Preference Detection"]
    end
    
    subgraph API["<b>🔌 API LAYER</b>"]
        APIClient["📡 Axios Client<br/>JWT Interceptor"]
        APIMethods["🛠️ API Methods<br/>Auth, Jobs, Applications,<br/>Profile, Resume, Assistant"]
    end
    
    subgraph Utils["<b>🛠️ UTILITIES</b>"]
        Hooks["🪝 Custom Hooks<br/>useAuth, useDebounce"]
        Types["📝 TypeScript Types<br/>User, Job, Application"]
        Helpers["⚙️ Helper Functions<br/>formatDate, validateEmail"]
    end
    
    subgraph Backend["<b>🚀 BACKEND</b>"]
        FastAPI["FastAPI REST API<br/>http://localhost:8000"]
    end
    
    %% Connections
    PublicRoutes ==> Layout
    JSRoutes ==> Layout
    EMPRoutes ==> Layout
    
    PublicRoutes ==> Features
    JSRoutes ==> Features
    EMPRoutes ==> Features
    
    Layout ==> UI
    Features ==> UI
    
    Features ==> AuthStore
    Layout ==> AuthStore
    Layout ==> ThemeContext
    
    Features ==> APIClient
    AuthStore ==> APIClient
    ThemeContext -.->|"Theme Preference"| Layout
    
    APIClient ==> APIMethods
    APIMethods ==> FastAPI
    
    Features ==> Hooks
    Features ==> Types
    APIClient ==> Helpers
    
    %% Styling
    classDef routesStyle fill:#e3f2fd,stroke:#1976d2,stroke-width:3px
    classDef componentsStyle fill:#e8f5e9,stroke:#388e3c,stroke-width:3px
    classDef stateStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px
    classDef apiStyle fill:#fff3e0,stroke:#f57c00,stroke-width:3px
    classDef utilsStyle fill:#fff9c4,stroke:#f57f17,stroke-width:3px
    classDef backendStyle fill:#fce4ec,stroke:#c2185b,stroke-width:3px
    
    class Routes routesStyle
    class Components componentsStyle
    class State stateStyle
    class API apiStyle
    class Utils utilsStyle
    class Backend backendStyle
    
    %% Link styling
    linkStyle default stroke:#333,stroke-width:3px

Frontend Flow Explained in Simple Terms

Think of the frontend as a restaurant experience:

1. 🚪 The Entrance (App Router)

When you visit the website, the App Router is like the restaurant's entrance
It decides which "room" (page) you should go to based on the URL
Example: /login takes you to the login page, /dashboard takes you to your dashboard

2. 📄 The Rooms (Pages)

Each page is like a different room in the restaurant
Public rooms: Anyone can enter (Home, Jobs, Login)
Private rooms: Need a key to enter (Dashboard, Profile)
VIP rooms: Only for special guests (Employer Dashboard)

3. 🧩 The Furniture (Components)

Components are like furniture pieces you can reuse in different rooms
Layout furniture: Navbar (menu board), Footer (exit sign)
UI furniture: Buttons (chairs), Input boxes (tables), Cards (display cases)
Feature furniture: Login forms, job cards, application forms

4. 💾 The Memory (State Management)

The Zustand Store is like the restaurant's memory system
It remembers: "Is this customer logged in?" "What's their name?" "What's their access token?"
All rooms can check this memory to know who you are

5. 🔌 The Kitchen Phone (API Client)

The Axios Client is like a phone that calls the kitchen (backend)
When you click "Apply for Job", it calls the kitchen: "Hey, this person wants to apply!"
The kitchen processes your order and sends back a response
The phone automatically includes your "membership card" (JWT token) with every call

6. 🛠️ The Toolbox (Utilities)

Hooks: Special tools that help components do their job (like a can opener)
Types: Labels that describe what each thing is (TypeScript definitions)
Helpers: Small tools for common tasks (format dates, validate emails)

7. 🚀 The Kitchen (Backend)

The FastAPI Backend is like the restaurant's kitchen
It receives orders (API requests), cooks them (processes data), and sends back food (responses)
It checks your membership card (JWT) to make sure you're allowed to order

How It All Works Together:

Example 1: Job Seeker - Applying for a Job 👤

👤 You click "Apply" on a job listing
📄 Page shows you the application form (ApplyModal component)
✍️ You fill out the form and click "Submit"
🧩 Component collects your form data
💾 State provides your user info and token
🔌 API Client calls the backend: "POST /api/v1/applications" with your data + token
🚀 Backend receives the request, validates it, saves to database
📧 Backend sends you a confirmation email
🔌 API Client receives success response
🧩 Component shows you: "Application submitted successfully! ✅"
📄 Page updates to show your new application in the list

Example 2: Employer - Reviewing Applications 💼

💼 You (employer) navigate to "My Jobs" page
📄 Page loads your job listings
🔌 API Client calls: "GET /api/v1/jobs/employer/me" with your token
🚀 Backend checks your token, finds your jobs, returns the list
📄 Page displays your jobs using JobCard components
👆 You click on a job to see its applications
📄 Page navigates to the applications review page
🔌 API Client calls: "GET /api/v1/jobs/{job_id}/applications" with your token
🚀 Backend verifies you own this job, returns all applications
🧩 Component displays each application in a CandidateCard
👀 You review a candidate and click "Shortlist"
🔌 API Client calls: "POST /api/v1/applications/{id}/shortlist" with your token
🚀 Backend updates application status to "SHORTLISTED"
📧 Backend sends email to candidate: "Good news! You've been shortlisted!"
🔌 API Client receives success response
🧩 Component updates the card to show "Shortlisted" badge
📄 Page moves the card to the "Shortlisted" section

That's it! The frontend is just a well-organized system that:

Shows you pages and forms (UI)
Remembers who you are (State)
Talks to the backend (API)
Makes everything look nice and work smoothly (Components)
Works seamlessly for both Job Seekers and Employers

Frontend Architectural Highlights

🎯 Next.js 14 App Router

File-Based Routing: Automatic route generation from folder structure
Server Components: Default server-side rendering for optimal performance
Client Components: Interactive components with 'use client' directive
Nested Layouts: Shared layouts for dashboard and employer sections
Dynamic Routes: [id] for job details and application pages
Loading States: Built-in loading.tsx for better UX

🧩 Component Architecture

Atomic Design: UI components (Button, Input) → Feature components (LoginForm) → Pages
Reusability: 40+ components designed for maximum reuse
Composition: Complex features built from simple UI components
Props Interface: Strict TypeScript interfaces for all component props
Feature Folders: Related components grouped by feature (auth, jobs, profile, etc.)

📦 State Management Strategy

Global State (Zustand): Authentication state (user, token, isAuthenticated)
Theme State (Context API): Dark mode theme with system preference detection
Local State (useState): Component-specific UI state (modals, dropdowns)
Form State (React Hook Form): Form data with validation
Server State: API responses managed with React patterns
Persistent State: JWT token and theme preference stored in localStorage

🔌 API Integration

Centralized Client: Single api.ts file with all API methods
Axios Instance: Configured with base URL and JWT interceptor
Automatic Auth: JWT token automatically attached to all requests
Rate Limit Handling: 429 error detection with user-friendly messages
Error Handling: Consistent error handling across all API calls with specific messages for rate limits
Type Safety: All API methods have TypeScript return types
Retry Logic: Graceful handling of temporary failures

🎨 Styling System

Tailwind CSS: Utility-first CSS framework with dark mode support
Custom Design System: Consistent colors, spacing, and typography
TalentNest Branding: Primary blue (#075299) used throughout
Responsive Design: Mobile-first approach with breakpoints
Dark Mode: Fully implemented with Theme Context, localStorage persistence, and system preference detection
CSS Variables: Dynamic theme colors for seamless light/dark transitions
Smooth Transitions: Theme switching with fade animations

🔐 Authentication Flow

User Registration/Login → Form submission
API Call → api.register() or api.login()
Token Received → JWT token from backend
Store Update → Zustand setUser() and setToken()
LocalStorage → Token persisted for page refreshes
Route Protection → Middleware checks auth state
Role-Based Routing → Redirect to appropriate dashboard

🛣️ Routing Strategy

Public Routes: /, /jobs, /jobs/[id], /login, /register
Job Seeker Routes: /dashboard/* (protected)
Employer Routes: /employer/* (protected)
Role-Based Access: Middleware checks user role for access control
Automatic Redirects: Unauthenticated users redirected to login

📱 Responsive Design

Mobile-First: Base styles for mobile, enhanced for desktop
Breakpoints: sm:, md:, lg:, xl: for different screen sizes
Flexible Layouts: Grid and flexbox for adaptive layouts
Touch-Friendly: Large tap targets for mobile users
Sidebar Collapse: Dashboard sidebar collapses on mobile

⚡ Performance Optimizations

Code Splitting: Automatic route-based code splitting
Lazy Loading: Components loaded on demand
Image Optimization: Next.js Image component for optimized images
Bundle Size: Tree-shaking removes unused code
Production Build: Minified and optimized for production

🧪 Type Safety

TypeScript: Strict type checking throughout
Interface Definitions: All data structures typed in types/index.ts
API Response Types: Backend responses have matching frontend types
Component Props: All props strictly typed
Compile-Time Safety: Catch errors before runtime

🎭 User Experience

Loading States: Skeleton screens and spinners during data fetch
Error Handling: User-friendly error messages including rate limit notifications
Form Validation: Real-time validation with helpful messages
Success Feedback: Toast notifications for successful actions
Empty States: Helpful messages when no data available
Smooth Transitions: CSS transitions for better feel
Password Visibility Toggle: Eye icon for secure password entry
Enhanced Navigation: Clear labeling for Employer Dashboard

🌓 Dark Mode Implementation

Theme Context: React Context API for global theme state management
System Preference Detection: Automatically detects user's OS theme preference
Manual Toggle: Theme switcher in Navbar (desktop and mobile)
LocalStorage Persistence: Theme preference saved across sessions
Smooth Transitions: Fade animations when switching themes
CSS Variables: Dynamic color variables for seamless theme switching
Component Support: All UI components styled for both light and dark modes
Accessibility: Maintains WCAG contrast ratios in both themes

📊 Entity Relationship Diagram (ERD)

Database Schema - MongoDB Collections

The following ERD shows the MongoDB collections and their relationships in the TalentNest Job Portal:

%%{init: {'theme':'default', 'themeVariables': { 'lineColor':'#999999', 'primaryBorderColor':'#999999'}}}%%
erDiagram
    User ||--o{ Resume : "has"
    User ||--o{ Application : "submits"
    User ||--o{ Conversation : "has"
    User ||--|| Company : "creates (employer)"
    
    Company ||--o{ Job : "posts"
    
    Job ||--o{ Application : "receives"
    Job ||--o{ Interview : "schedules"
    
    Application ||--o| Resume : "references"
    Application ||--o| Interview : "leads to"
    
    User {
        ObjectId _id PK
        string email UK
        string hashed_password
        string full_name
        string role
        string phone
        string location
        array skills
        string experience
        string education
        datetime created_at
        datetime updated_at
    }
    
    Company {
        ObjectId _id PK
        ObjectId employer_id FK
        string name
        string description
        string industry
        string website
        string location
        int company_size
        datetime created_at
        datetime updated_at
    }
    
    Job {
        ObjectId _id PK
        ObjectId employer_id FK
        ObjectId company_id FK
        string title
        string description
        string requirements
        array skills
        string location
        string job_type
        string experience_level
        int salary_min
        int salary_max
        string status
        datetime posted_date
        datetime deadline
        datetime created_at
        datetime updated_at
    }
    
    Application {
        ObjectId _id PK
        ObjectId job_id FK
        ObjectId applicant_id FK
        ObjectId resume_id FK
        string status
        string cover_letter
        datetime applied_date
        datetime updated_at
        string notes
    }
    
    Resume {
        ObjectId _id PK
        ObjectId user_id FK
        string file_url
        string file_name
        string parsed_text
        array skills_extracted
        string experience_extracted
        string education_extracted
        datetime created_at
        datetime updated_at
    }
    
    Conversation {
        ObjectId _id PK
        ObjectId user_id FK
        array messages
        string context_type
        datetime created_at
        datetime updated_at
    }
    
    Interview {
        ObjectId _id PK
        ObjectId job_id FK
        ObjectId application_id FK
        ObjectId employer_id FK
        ObjectId candidate_id FK
        datetime scheduled_time
        int duration_minutes
        string status
        string meeting_link
        string location
        string notes
        datetime created_at
        datetime updated_at
    }

Collection Relationships Explained

User Collection

Central entity for both job seekers and employers
Role field determines user type: "job_seeker" or "employer"
One-to-Many with Resume (job seekers can upload multiple resumes)
One-to-Many with Application (job seekers submit multiple applications)
One-to-Many with Conversation (users have chat history with AI assistant)
One-to-One with Company (employers create their company profile)

Company Collection

Owned by employer users
One-to-Many with Job (companies post multiple job listings)
Contains company branding and information

Job Collection

Posted by employers through their company
One-to-Many with Application (jobs receive multiple applications)
One-to-Many with Interview (jobs can have multiple interview schedules)
Stores job requirements, skills, salary range, and status

Application Collection

Links job seekers to jobs
References a specific resume from the applicant
Status tracking: pending → reviewing → shortlisted → rejected/accepted
One-to-One with Interview (shortlisted applications lead to interviews)

Resume Collection

Belongs to job seekers
Stores uploaded file and AI-parsed data
Extracted skills, experience, and education used for AI recommendations

Conversation Collection

Stores AI assistant chat history
Array of messages with role (user/assistant) and content
Enables context-aware conversations

Interview Collection (BONUS Feature)

Schedules interviews between employers and candidates
Links to both Job and Application
Tracks interview status: scheduled → completed → cancelled
Stores meeting link and location details

Key Database Features

✅ MongoDB with Beanie ODM - Async operations with Pydantic validation
✅ Indexed Fields - Optimized queries on email, job_id, user_id, status
✅ Embedded Documents - Messages array in Conversation for efficiency
✅ Referential Integrity - Foreign keys maintained through ObjectId references
✅ Timestamps - Automatic created_at and updated_at tracking
✅ Flexible Schema - MongoDB's document model allows easy schema evolution

🚀 Features

For Job Seekers

📝 Profile Management - Create and update professional profiles
📄 Resume Upload - Upload PDF/DOCX resumes with AI parsing (GPT-4o)
🔍 Job Search - Search and filter jobs by location, type, experience level
💼 Apply to Jobs - Submit applications with AI-generated cover letters
📊 Application Tracking - Monitor application status in real-time with email notifications
🤖 AI Recommendations - Get personalized job matches using ChromaDB vector embeddings + AI scoring
💬 AI Career Assistant - RAG-based chatbot with context-aware career guidance
📅 Interview Management - View and manage scheduled interviews with calendar integration
🌙 Dark Mode - System-aware theme switching for comfortable viewing

For Employers

📢 Job Posting - Create, edit, and manage job listings with full CRUD operations
👥 Application Review - View and manage candidate applications with status tracking
✅ Candidate Actions - Shortlist, reject, or update application status with automated emails
📧 Email Notifications - Automated SMTP notifications for all application events
🎯 AI Candidate Matching - Get AI-powered candidate recommendations using vector similarity + AI scoring
📊 Dashboard Analytics - Track job postings and application metrics
📅 Interview Scheduling - Schedule, reschedule, and manage candidate interviews
🔔 Real-time Updates - Instant application status updates

AI-Powered Features (Production-Grade)

🧠 Resume Parsing - GPT-4o extracts skills, experience, and education from resumes
📝 Cover Letter Generation - AI-generated personalized cover letters with job context
🎯 Job Recommendations - Hybrid scoring: 70% ChromaDB vector similarity + 30% AI analysis
🤝 Candidate Matching - Hybrid scoring: 70% ChromaDB vector similarity + 30% AI analysis
💬 RAG Assistant - Retrieval-Augmented Generation chatbot with job portal knowledge
🔄 AI Provider Fallback - Automatic failover between OpenAI GPT-4o and Anthropic Claude
🔗 LangChain Integration - Structured AI workflows with prompt chains
🤖 n8n Workflow Automation - Optional AI orchestration for complex workflows
📊 Vector Embeddings - OpenAI text-embedding-3-small with HuggingFace fallback

Production Features

🔐 Security - JWT authentication, bcrypt hashing, CORS, rate limiting
🚦 Rate Limiting - Configurable limits on all critical endpoints (5-30 req/min)
📝 Structured Logging - Separate app and HTTP logs with configurable levels
🐳 Docker Ready - Multi-stage builds with health checks and volume management
🎨 Responsive Design - Mobile-first design with Tailwind CSS
⚡ Performance - Async/await, connection pooling, code splitting
🧪 Testing Tools - GUI testing tracker with MongoDB integration
📚 Documentation - Comprehensive docs with Mermaid diagrams (ERD, Architecture, Flow)

🛠️ Tech Stack

Backend

Framework: FastAPI (Python 3.11+) with async/await
Database: MongoDB Atlas with Beanie ODM
Authentication: JWT with bcrypt password hashing
AI/ML:
- OpenAI GPT-4o (primary) with Anthropic Claude fallback
- ChromaDB for vector storage and semantic search
- LangChain for AI orchestration and prompt chains
- OpenAI text-embedding-3-small for embeddings
- HuggingFace all-MiniLM-L6-v2 (fallback embeddings)
Workflow Automation: n8n integration (optional)
Email: SMTP with aiosmtplib for notifications
File Processing: PyPDF2, python-docx for resume parsing
Validation: Pydantic v2 for data validation
Rate Limiting: slowapi for API protection
Logging: Structured logging with configurable levels

Frontend

Framework: Next.js 14 (App Router)
Language: TypeScript with strict type checking
Styling: Tailwind CSS with custom design system
State Management: Zustand for auth and global state
HTTP Client: Axios with JWT interceptor
Forms: React Hook Form with validation
Icons: Lucide React
Theme: Dark mode with system preference detection

AI & Machine Learning

Vector Database: ChromaDB (persistent + in-memory)
Embeddings: OpenAI text-embedding-3-small (primary), HuggingFace (fallback)
LLM Providers: OpenAI GPT-4o, Anthropic Claude 3.5 Sonnet
AI Orchestration: LangChain with custom prompt chains
RAG Pipeline: Document loader, text splitter, vector retriever, QA chain
Workflow Automation: n8n for complex AI workflows (optional)
Hybrid Scoring: 70% vector similarity + 30% AI analysis

DevOps & Production

Containerization: Docker with multi-stage builds
Orchestration: Docker Compose
Database: MongoDB Atlas (cloud) or local MongoDB
Environment: .env configuration management
Health Checks: Container health monitoring
Logging: Structured JSON and text logging
Rate Limiting: Configurable per-endpoint limits
Security: CORS, JWT, bcrypt, input validation

📦 Installation & Setup

Prerequisites

Python 3.11 or higher
Node.js 20 or higher
MongoDB Atlas account (or local MongoDB)
Docker & Docker Compose (for containerized deployment)
OpenAI API key (required for AI features) or Anthropic API key (fallback option)
SMTP credentials (optional, for email notifications)

Option 1: Docker Setup (Recommended)

Clone the repository:
```
git clone <repository-url>
cd JobPortal
```

Set up environment variables:

# Backend
cp backend/.env.example backend/.env
# Edit backend/.env with your actual values

# Frontend
cp frontend/.env.example frontend/.env.local
# Edit frontend/.env.local with your actual values

Build and run with Docker Compose:

# From project root
docker-compose -f docker/docker-compose.yml up --build

# Or from docker directory
cd docker
docker-compose up --build

Access the application:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs

Stop the application:

# From project root
docker-compose -f docker/docker-compose.yml down

# Or from docker directory
cd docker
docker-compose down

For detailed Docker documentation, see docker/README.md

Option 2: Manual Setup

Backend Setup

Navigate to backend directory:
```
cd backend
```

Create and activate virtual environment:

# Windows
python -m venv venv
.\venv\Scripts\Activate.ps1

# Linux/Mac
python3 -m venv venv
source venv/bin/activate

Install dependencies:
```
pip install -r requirements.txt
```

Set up environment variables:

cp .env.example .env
# Edit .env with your actual values

Run the backend:

# Python 3.13+ on Windows (no auto-reload)
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

# Python < 3.13 or Linux/Mac (with auto-reload)
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

Frontend Setup

Navigate to frontend directory:
```
cd frontend
```
Install dependencies:
```
npm install
```

Set up environment variables:

cp .env.example .env.local
# Edit .env.local with your actual values

Run the frontend:
```
npm run dev
```
Access the application:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000

🔧 Configuration

Backend Environment Variables

Required variables in backend/.env:

MONGODB_URI: MongoDB connection string
DATABASE_NAME: Database name (default: jobportal)
SECRET_KEY: JWT secret key (generate a strong random string)
CORS_ORIGINS: Allowed origins (e.g., http://localhost:3000)

AI Provider Configuration (at least one required for AI features):

AI_PROVIDER: Primary AI provider ("openai" or "anthropic", default: "openai")
AI_FALLBACK_ENABLED: Enable automatic fallback (default: true)
OPENAI_API_KEY: OpenAI API key for GPT-4o
OPENAI_MODEL: OpenAI model (default: "gpt-4o")
ANTHROPIC_API_KEY: Anthropic API key for Claude (fallback)
ANTHROPIC_MODEL: Anthropic model (default: "claude-3-5-sonnet-20241022")

Optional but recommended:

SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD: For email notifications
N8N_BASE_URL, N8N_API_KEY: For n8n workflow automation (optional)
CHROMADB_PATH: Persistent vector store path (optional, defaults to in-memory)

Production settings:

HOST: Server host (default: "127.0.0.1", use "0.0.0.0" for Docker)
PORT: Server port (default: 8000)
LOG_LEVEL: Application log level (default: "INFO")
UVICORN_LOG_LEVEL: Uvicorn log level (default: "info")
RATE_LIMIT_ENABLED: Enable rate limiting (default: true)
RATE_LIMIT_AUTH_PER_MINUTE: Auth endpoint limit (default: 5)
RATE_LIMIT_AI_PER_MINUTE: AI endpoint limit (default: 30)

See backend/.env.example for all available options.

Frontend Environment Variables

Required variables in frontend/.env.local:

NEXT_PUBLIC_API_URL: Backend API URL (default: http://localhost:8000)

📚 API Documentation

Once the backend is running, visit:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

🧪 Testing

Manual Testing with GUI Test Tracker

The project includes an independent GUI testing tool for comprehensive manual test tracking:

cd testing_tool

# Install dependencies (if not already installed)
pip install -r requirements.txt

# Run the testing tool
python test_tracker.py

Features:

📊 Comprehensive Test Coverage: 100+ test cases covering all features
💾 Progress Saving: Save and resume test sessions
👥 Team Collaboration: Merge results from multiple testers
🎯 Quick Navigation: Jump to specific test sections
📈 Real-time Progress: Track pass/fail/block statistics
📝 Detailed Reporting: Generate markdown test reports
🔄 Browser Mode Selection: Test across different browsers

For detailed documentation, see testing_tool/README.md

Backend Testing

cd backend
pytest

Frontend Testing

cd frontend
npm test

🐳 Docker Commands

All Docker files are located in the docker/ directory.

Build images

docker-compose -f docker/docker-compose.yml build

Run in detached mode

docker-compose -f docker/docker-compose.yml up -d

View logs

docker-compose -f docker/docker-compose.yml logs -f

Stop containers

docker-compose -f docker/docker-compose.yml down

Remove volumes

docker-compose -f docker/docker-compose.yml down -v

Rebuild and restart

docker-compose -f docker/docker-compose.yml up --build --force-recreate

For more Docker commands and troubleshooting, see docker/README.md

📁 Project Structure

JobPortal/
├── backend/                    # FastAPI backend
│   ├── app/
│   │   ├── ai/                # AI features & orchestration
│   │   │   ├── agents/        # AI agents
│   │   │   ├── chains/        # LangChain recommendation & matching chains
│   │   │   ├── prompts/       # AI prompt templates
│   │   │   ├── providers/     # AI provider abstraction (OpenAI, Anthropic)
│   │   │   │   ├── base.py    # Abstract base provider
│   │   │   │   ├── openai_provider.py   # OpenAI implementation
│   │   │   │   ├── anthropic_provider.py # Anthropic implementation
│   │   │   │   └── factory.py # Provider factory with auto-fallback
│   │   │   └── rag/           # RAG pipeline (embeddings, vectorstore, QA chain)
│   │   ├── api/               # API routes with rate limiting
│   │   │   └── v1/routes/     # Auth, jobs, applications, assistant, interviews, etc.
│   │   ├── core/              # Core configuration (settings, security, logging)
│   │   ├── db/                # Database initialization
│   │   ├── integrations/      # External integrations (n8n client)
│   │   ├── models/            # Beanie ODM models (User, Job, Application, Interview, etc.)
│   │   ├── repositories/      # Data access layer
│   │   ├── schemas/           # Pydantic request/response schemas
│   │   ├── services/          # Business logic (email, resume parser, recommendations, matching)
│   │   ├── templates/         # Email templates
│   │   ├── workers/tasks/     # Background tasks
│   │   └── main.py            # FastAPI application entry point
│   ├── uploads/resumes/       # Uploaded resume files
│   ├── chroma_db/             # ChromaDB persistent vector store
│   ├── .env.example           # Environment template with all config options
│   ├── requirements.txt       # Python dependencies (FastAPI, LangChain, ChromaDB, etc.)
│   ├── TESTING_BACKEND.md     # Backend testing guide
│   └── README.md              # Backend documentation with setup instructions
├── frontend/                  # Next.js 14 frontend with dark mode
│   ├── app/                   # App Router pages
│   │   ├── dashboard/         # Job seeker pages (profile, applications, recommendations, assistant, interviews)
│   │   ├── employer/          # Employer pages (dashboard, jobs, applications, interviews)
│   │   ├── jobs/              # Job listings and details
│   │   ├── login/             # Login page with password visibility toggle
│   │   ├── register/          # Registration page
│   │   └── layout.tsx         # Root layout with theme provider
│   ├── components/            # Reusable UI components
│   │   ├── layout/            # Navbar (with theme toggle), Footer, DashboardLayout
│   │   └── ui/                # Button, Input, Card, Modal, Badge, etc.
│   ├── context/               # React Context providers
│   │   └── ThemeContext.tsx   # Dark mode theme context
│   ├── features/              # Feature-specific components
│   │   ├── auth/              # Login/Register forms
│   │   ├── jobs/              # Job cards, filters, apply modal
│   │   ├── profile/           # Profile forms
│   │   ├── recommendations/   # AI job recommendations
│   │   ├── assistant/         # AI chat interface, cover letter generator
│   │   └── employer/          # Employer-specific components (candidate recommendations)
│   ├── hooks/                 # Custom React hooks (useAuth, useTheme, etc.)
│   ├── lib/                   # API client with JWT & rate limit handling
│   ├── public/                # Static assets (logo-bird.png, etc.)
│   ├── store/                 # Zustand state management (auth store)
│   ├── styles/                # Global styles with dark mode support
│   ├── types/                 # TypeScript type definitions
│   ├── constants/             # Application constants (status mappings, etc.)
│   ├── .env.example           # Environment template
│   ├── package.json           # Node dependencies
│   ├── tailwind.config.ts     # Tailwind CSS configuration with dark mode
│   ├── FRONTEND_GUIDE.md      # Frontend guide
│   └── README.md              # Frontend documentation with cross-platform instructions
├── docker/                    # Docker configuration
│   ├── backend.Dockerfile     # Backend Docker image (multi-stage build)
│   ├── frontend.Dockerfile    # Frontend Docker image (multi-stage build)
│   ├── docker-compose.yml     # Multi-container orchestration
│   ├── env.example            # Docker environment template
│   ├── .dockerignore          # Docker ignore files
│   └── README.md              # Docker setup guide with OS-specific instructions
├── testing_tool/              # GUI testing tracker
│   ├── test_tracker.py        # MongoDB-integrated testing tool (v2.1.3)
│   ├── requirements.txt       # Testing tool dependencies
│   ├── results/               # Test results and reports
│   └── README.md              # Testing tool documentation
├── DB_ContentGen/             # Database seeding utilities
│   ├── candidate_generator.py # Generate test candidates
│   ├── employer_generator.py  # Generate test employers
│   ├── job_generator.py       # Generate test jobs
│   ├── application_generator.py # Generate test applications
│   └── README.md              # Database seeding documentation
├── docs/                      # Project documentation
│   ├── SPECIFICATION_COMPLIANCE_REVIEW.md  # Spec compliance verification
│   ├── IMPLEMENTATION_VERIFICATION.md      # Implementation verification
│   ├── SPEC_TO_IMPLEMENTATION_ANALYSIS.md  # Detailed analysis
│   ├── PROJECT_IMPLEMENTATION_VERIFICATION.md # Project verification
│   ├── N8N_COMPLIANCE_VERIFICATION.md      # n8n integration verification
│   ├── DOCKER_SETUP_VERIFICATION.md        # Docker setup verification
│   ├── TEST_TRACKER_COMPLIANCE_REVIEW.md   # Testing tool compliance
│   └── N8N_WORKFLOWS.md        # n8n workflow documentation
├── project-spec/              # Project specifications
│   ├── Presentation/          # Presentation guidelines
│   └── *.md                   # Detailed project specs and walkthroughs
├── images/                    # Project images and assets
│   └── TalentNest.png         # Original logo
├── scripts/                   # Utility scripts
│   ├── shrink_hat.py          # Image processing script
│   └── crop_bird_hat.py       # Logo generation script
├── JobPortal Implementation Plan.md  # Complete implementation roadmap
├── TESTING_REPORT.md          # Phase 1 testing report
├── FRONTEND_GUIDE.md          # Complete frontend guide
├── FRONTEND_COMPLETION_SUMMARY.md  # Frontend feature checklist
├── CONTRIBUTING.md            # Contribution guidelines
└── README.md                  # This file (comprehensive project documentation)

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feat/feature-name)
Commit your changes (git commit -m 'Add feature')
Push to the branch (git push origin feat/feature-name)
Open a Pull Request

📝 License

This project is part of an academic assignment.

👥 Team

Developed as part of a collaborative software engineering project.

🗄️ Database Seeding

To populate the database with sample data for testing and development:

cd DB_ContentGen

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp env_example.txt .env
# Edit .env with your MongoDB credentials

# Generate sample data
python candidate_generator.py    # Generate job seekers
python employer_generator.py     # Generate employers
python job_generator.py          # Generate job postings
python application_generator.py  # Generate applications

See DB_ContentGen/README.md for detailed instructions.

🐛 Troubleshooting

Common Issues

Backend won't start:

Ensure Python 3.11+ is installed: python --version
Check MongoDB connection string in .env
Verify all dependencies are installed: pip install -r requirements.txt
For Python 3.13 on Windows: Auto-reload is disabled (known issue)

Frontend won't start:

Ensure Node.js 20+ is installed: node --version
Clear cache: rm -rf .next node_modules && npm install
Check NEXT_PUBLIC_API_URL in .env.local

Docker issues:

Port conflicts: Stop services using ports 3000, 8000, or 27017
Permission errors: Run Docker as administrator (Windows) or with sudo (Linux)
Build failures: Clear Docker cache: docker system prune -a
See docker/README.md for comprehensive troubleshooting

Database connection errors:

Verify MongoDB Atlas credentials
Check IP whitelist in MongoDB Atlas (allow 0.0.0.0/0 for development)
Test connection: python backend/test_connectivity_to_mongoDB.py

AI features not working:

Verify OPENAI_API_KEY is set in backend .env
Check OpenAI API quota and billing
AI features gracefully degrade if API key is missing

For more help, see individual component READMEs or check the TESTING_REPORT.md.

📚 Documentation

Core Documentation

Implementation Plan - Complete development roadmap with all phases
Testing Report - Phase 1 testing results and bug fixes
Frontend Guide - Complete frontend documentation
Frontend Completion Summary - Feature checklist

Component Documentation

Backend Testing Guide - API testing instructions
Backend README - Backend-specific documentation
Frontend README - Frontend-specific documentation
Docker README - Docker setup with OS-specific instructions
DB Content Generator - Database seeding guide

Project Specifications

Project Spec 1 - Project overview
Project Spec 2 - Frontend walkthrough
Project Spec 3 - Backend walkthrough
Project Spec 4-6 - Setup and workflow guides

🧪 Testing

Manual Testing

All Phase 1 features have been tested and documented in TESTING_REPORT.md.

Test Coverage:

✅ User registration and login
✅ JWT authentication and protected routes
✅ Role-based routing (Job Seeker / Employer)
✅ Database connectivity
✅ Password hashing and security

Backend Testing

cd backend
python test_connectivity_to_mongoDB.py  # Test database connection
python test_auth_endpoint.py            # Test authentication flow

See backend/TESTING_BACKEND.md for comprehensive API testing instructions.

Frontend Testing

cd frontend
npm run dev  # Start development server
# Manually test features through the UI

🎯 Production-Ready Features

Security & Authentication

✅ JWT Authentication - Stateless, secure token-based auth
✅ Password Hashing - Bcrypt with salt rounds
✅ Role-Based Access Control - Job Seeker vs Employer permissions
✅ Rate Limiting - Configurable limits per endpoint (5-30 req/min)
✅ CORS Configuration - Controlled cross-origin access
✅ Input Validation - Pydantic schemas for all requests
✅ Error Handling - Comprehensive exception handling

AI & Machine Learning

✅ Hybrid AI Scoring - 70% vector similarity + 30% AI analysis
✅ Provider Fallback - Automatic OpenAI ↔ Anthropic failover
✅ Vector Embeddings - ChromaDB with persistent storage
✅ LangChain Chains - Structured AI workflows
✅ RAG Pipeline - Context-aware AI assistant
✅ n8n Integration - Optional workflow automation
✅ Graceful Degradation - App works without AI keys

Performance & Scalability

✅ Async/Await - Non-blocking I/O throughout
✅ Connection Pooling - Efficient database connections
✅ Code Splitting - Automatic route-based splitting
✅ Multi-Stage Docker Builds - Optimized image sizes
✅ Health Checks - Container health monitoring
✅ Structured Logging - JSON and text formats
✅ Configurable Settings - Environment-based configuration

Developer Experience

✅ Comprehensive Documentation - README, ERD, architecture diagrams
✅ API Documentation - Auto-generated Swagger/ReDoc
✅ Type Safety - TypeScript frontend, Pydantic backend
✅ Testing Tools - GUI testing tracker with MongoDB
✅ Database Seeding - Comprehensive test data generators
✅ Colored Console - Enhanced visual feedback
✅ Hot Reload - Development auto-reload

User Experience

✅ Dark Mode - System-aware theme switching
✅ Responsive Design - Mobile-first with Tailwind
✅ Loading States - Skeleton screens and spinners
✅ Error Messages - User-friendly validation feedback
✅ Email Notifications - SMTP notifications for all events
✅ Real-time Updates - Instant status changes
✅ Password Toggle - Enhanced security UX

🚀 Deployment

Docker Deployment (Recommended)

The application is production-ready and fully containerized:

# Production build
docker-compose -f docker/docker-compose.yml up -d --build

# View logs
docker-compose -f docker/docker-compose.yml logs -f

# Stop services
docker-compose -f docker/docker-compose.yml down

Production Checklist

Before deploying to production:

Security:

✅ Generate a strong SECRET_KEY for JWT (32+ characters)
✅ Configure production MongoDB URI with authentication
✅ Set up SMTP credentials for email notifications
✅ Add OpenAI API key (and optionally Anthropic for fallback)
✅ Configure CORS origins for your production domain
✅ Enable HTTPS/SSL with reverse proxy (nginx/Caddy)
✅ Set RATE_LIMIT_ENABLED=true for API protection

Configuration: 8. ✅ Set HOST=0.0.0.0 for Docker deployment 9. ✅ Configure LOG_LEVEL=INFO for production 10. ✅ Set up CHROMADB_PATH for persistent vector storage 11. ✅ Configure n8n if using workflow automation 12. ✅ Set up monitoring and logging aggregation 13. ✅ Configure backup strategy for MongoDB

Optional Enhancements:

Set up Redis for caching (future enhancement)
Configure CDN for static assets
Set up load balancer for horizontal scaling
Implement monitoring (Prometheus, Grafana)
Set up error tracking (Sentry)

See docker/README.md for comprehensive production deployment guide.

🔗 Quick Links

🏆 Project Highlights

What Makes This Production-Ready?

Complete Feature Set - All planned features fully implemented and tested
AI Excellence - Hybrid scoring with vector embeddings + LLM analysis
Provider Redundancy - Automatic failover between OpenAI and Anthropic
Security First - JWT, bcrypt, rate limiting, CORS, input validation
Scalable Architecture - Async/await, connection pooling, Docker-ready
Developer Friendly - Comprehensive docs, type safety, testing tools
Production Tested - All phases complete with verification reports

Documentation

This project includes extensive documentation:

✅ README.md (this file) - 1200+ lines of comprehensive documentation
✅ Implementation Plan - Complete 4-phase development roadmap
✅ Specification Compliance - 100% compliance verification
✅ Implementation Verification - Detailed feature verification report
✅ Architecture Diagrams - ERD, System, Frontend, Flow (Mermaid)
✅ Docker Guide - Complete containerization documentation
✅ Testing Documentation - Manual tests and GUI testing tool

Ready for Production

✅ All 4 phases complete
✅ 100% specification compliant
✅ 11 bonus features beyond spec
✅ Comprehensive testing
✅ Production-grade security
✅ Docker deployment ready
✅ Fully documented

Status: PRODUCTION READY 🚀

Built with ❤️ as part of AI Vibe Coding course at Arizona State University

Name		Name	Last commit message	Last commit date
DB_ContentGen		DB_ContentGen
backend		backend
docker		docker
docs		docs
frontend		frontend
images		images
project-spec		project-spec
scripts		scripts
testing_tool		testing_tool
.gitignore		.gitignore
JobPortal Implementation Plan.md		JobPortal Implementation Plan.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

TalentNest Job Portal

👥 Development Team

📊 Project Status

✅ All Features Implemented

Phase 1: Foundation ✅ COMPLETE

Phase 2: Core Features ✅ COMPLETE

Phase 3: AI Features ✅ COMPLETE

Phase 4: Polish & Deployment ✅ COMPLETE

🎁 Bonus Features (Beyond Specification)

🏗️ System Architecture

System Flow Diagram

Detailed System Architecture Diagram

Key Architectural Highlights

🎯 Separation of Concerns

🔐 Security Architecture

🚀 Performance Optimizations

🤖 AI Integration & Orchestration

📧 Communication Layer

📊 Enhanced Data Flow

🔄 State Management

🐳 Containerization & Deployment

🎨 Frontend Architecture

Frontend Flow Diagram

Detailed Frontend Architecture Diagram

Frontend Flow Explained in Simple Terms

1. 🚪 The Entrance (App Router)

2. 📄 The Rooms (Pages)

3. 🧩 The Furniture (Components)

4. 💾 The Memory (State Management)

5. 🔌 The Kitchen Phone (API Client)

6. 🛠️ The Toolbox (Utilities)

7. 🚀 The Kitchen (Backend)

How It All Works Together:

Example 1: Job Seeker - Applying for a Job 👤

Example 2: Employer - Reviewing Applications 💼

Frontend Architectural Highlights

🎯 Next.js 14 App Router

🧩 Component Architecture

📦 State Management Strategy

🔌 API Integration

🎨 Styling System

🔐 Authentication Flow

🛣️ Routing Strategy

📱 Responsive Design

⚡ Performance Optimizations

🧪 Type Safety

🎭 User Experience

🌓 Dark Mode Implementation

📊 Entity Relationship Diagram (ERD)

Database Schema - MongoDB Collections

Collection Relationships Explained

User Collection

Company Collection

Job Collection

Application Collection

Resume Collection

Conversation Collection

Interview Collection (BONUS Feature)

Key Database Features

🚀 Features

For Job Seekers

For Employers

AI-Powered Features (Production-Grade)

Production Features

🛠️ Tech Stack

Backend

Frontend

AI & Machine Learning

DevOps & Production

📦 Installation & Setup

Prerequisites

Option 1: Docker Setup (Recommended)

Option 2: Manual Setup

Backend Setup

Frontend Setup

🔧 Configuration