PrepAI - Complete Architecture Guide

Version: 1.0.0 Last Updated: October 17, 2025 Status: Phase 4 Complete - Production Ready

System Overview
Architecture Diagram
Technology Stack
Component Breakdown
Data Flow
API Reference
Infrastructure
Security
Performance
Deployment

System Overview

PrepAI is an AI-powered interview preparation platform that provides real-time voice interviews using AWS Bedrock Agents, with advanced features including:

Real-time voice conversations (Speech-to-Text → AI Agent → Text-to-Speech)
Live code execution with quality analysis
Resume parsing using AWS Textract
Performance evaluation with benchmarking
Multi-modal interaction (voice, text, code)

Key Features

✅ 8 Interview Types (Google SDE, AWS SA, Azure SA, GCP SA, Microsoft SDE, Amazon SDE, Behavioral, Coding) ✅ Real-time voice communication with Whisper STT & Coqui TTS ✅ Bedrock Agent with Knowledge Base (RAG) integration ✅ 3 Lambda tools (Code Executor, CV Analyzer, Performance Evaluator) ✅ Code quality metrics & submission tracking ✅ PDF/DOCX resume parsing with industry-specific skills ✅ Performance analytics with benchmarks & trends ✅ Beautiful React/Next.js frontend with Monaco editor

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│                           FRONTEND (Next.js 15)                          │
│                                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │  Home Page   │  │  Interview   │  │  Demo Pages  │  │ Components │ │
│  │              │  │     Page     │  │              │  │            │ │
│  │ - Interview  │  │ - Voice UI   │  │ - CV Upload  │  │ - CV       │ │
│  │   Selection  │  │ - WebSocket  │  │ - Code       │  │ - Code     │ │
│  │ - Candidate  │  │ - Real-time  │  │ - Dashboard  │  │ - Charts   │ │
│  │   Info       │  │   STT/TTS    │  │              │  │            │ │
│  └──────┬───────┘  └──────┬───────┘  └──────────────┘  └────────────┘ │
│         │                 │                                             │
└─────────┼─────────────────┼─────────────────────────────────────────────┘
          │                 │
          │    HTTP/WS      │
          ▼                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        BACKEND (FastAPI)                                 │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                         API ROUTERS                               │  │
│  │                                                                   │  │
│  │  Sessions  │  Interviews  │  Code  │  WebSocket  │  Analytics   │  │
│  │  ────────     ──────────    ─────    ──────────    ──────────   │  │
│  │  • Create     • Transcript  • Exec   • Voice      • Aggregate   │  │
│  │  • List       • Upload CV   • Track  • STT/TTS    • Benchmarks  │  │
│  │               • End         • Quality • Streaming  • Trends      │  │
│  │               • Report                             • History     │  │
│  └───────────────────────┬───────────────────────────────────────────┘  │
│                          │                                              │
│  ┌───────────────────────┴───────────────────────────────────────────┐ │
│  │                       SERVICES LAYER                               │ │
│  │                                                                    │ │
│  │  Bedrock    Lambda      S3        Textract    Whisper    TTS     │ │
│  │  Service    Service     Service   Service     (STT)      (Audio) │ │
│  │  ────────   ────────    ────────  ────────    ────────   ──────  │ │
│  │  • Agent    • Execute   • Sessions • PDF      • Fast     • Coqui │ │
│  │  • Stream   • CV        • CVs      • DOCX     • Whisper  • VITS  │ │
│  │  • Session  • Perf      • Reports  • Extract  • VAD      • 22kHz │ │
│  │  • Retry    • Invoke    • Audio    • Skills             │        │ │
│  └────────────────────────────────────────────────────────────────────┘ │
└──────────────────┬───────────────────────────┬─────────────────────────┘
                   │                           │
          ┌────────┴────────┐         ┌────────┴────────┐
          │                 │         │                 │
          ▼                 ▼         ▼                 ▼
┌──────────────────┐  ┌──────────────────────────────────────────┐
│   AWS BEDROCK    │  │            AWS SERVICES                   │
│                  │  │                                           │
│  ┌────────────┐  │  │  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │   Agent    │  │  │  │ Lambda   │  │    S3    │  │Textract│ │
│  │  (Haiku)   │  │  │  │          │  │          │  │        │ │
│  │            │  │  │  │ • Code   │  │ • Sessions│  │• PDF   │ │
│  │ • RAG      │  │  │  │   Exec   │  │ • CVs    │  │• DOCX  │ │
│  │ • Tools    │  │  │  │ • CV     │  │ • Reports│  │• Extract│
│  │ • Stream   │  │  │  │   Parse  │  │ • Audio  │  │        │ │
│  └────┬───────┘  │  │  │ • Perf   │  │          │  │        │ │
│       │          │  │  │   Eval   │  │          │  │        │ │
│  ┌────▼───────┐  │  │  └──────────┘  └──────────┘  └────────┘ │
│  │ Knowledge  │  │  │                                           │
│  │   Base     │  │  │  Bucket: prepai-user-data                │
│  │   (RAG)    │  │  │  - sessions/*.json                       │
│  │            │  │  │  - cvs/{session_id}/*.pdf                │
│  │ • Questions│  │  │  - reports/{session_id}/*.json           │
│  │ • Best     │  │  │  - recordings/{session_id}/*.wav         │
│  │   Practices│  │  │                                           │
│  └────────────┘  │  │  IAM Role: prepai-lambda-tools-role      │
│                  │  │  Permissions: Lambda, S3, Textract       │
└──────────────────┘  └──────────────────────────────────────────┘

         Data Storage & State Management
         ─────────────────────────────────
         • Sessions: S3 (JSON files)
         • Transcripts: S3 (embedded in sessions)
         • Code Submissions: S3 (embedded in sessions)
         • CV Analysis: S3 (embedded in sessions)
         • Performance Reports: S3 (separate files)

Technology Stack

Frontend

Framework: Next.js 15.5.4 (React 19.1.0)
Language: TypeScript 5
Styling: Tailwind CSS 4
Build: Turbopack
Package Manager: npm

Key Libraries:
  - @monaco-editor/react: 4.7.0      # Code editor
  - recharts: 3.2.1                   # Charts
  - react-dropzone: 14.3.8            # File upload
  - jspdf: 3.0.3                      # PDF export
  - html2canvas: 1.4.1                # DOM to image
  - lucide-react: 0.546.0             # Icons

Backend

Framework: FastAPI (Python 3.11)
ASGI Server: Uvicorn
Package Manager: pip

Key Libraries:
  - boto3                             # AWS SDK
  - faster-whisper                    # Speech-to-Text
  - TTS (Coqui)                       # Text-to-Speech
  - PyPDF2                            # PDF fallback
  - pydantic                          # Data validation

AWS Services

Compute:
  - Lambda (3 functions: Code, CV, Performance)
  - Bedrock Agent (Haiku 3.5 model)

Storage:
  - S3 (prepai-user-data bucket)

AI/ML:
  - Bedrock Agent Runtime
  - Bedrock Knowledge Base
  - Textract (document analysis)

Networking:
  - CloudFormation (infrastructure)
  - IAM (permissions)

Development Tools

Infrastructure: AWS SAM CLI
Version Control: Git
API Testing: FastAPI Swagger UI
Documentation: Markdown

Component Breakdown

Frontend Components

1. Pages

app/
├── page.tsx                          // Home - Interview selection
├── interview/new/page.tsx            // Live interview session
└── demo/
    ├── page.tsx                      // Demo hub
    ├── cv/page.tsx                   // CV upload demo
    ├── code-editor/page.tsx          // Code editor demo
    └── performance/page.tsx          // Dashboard demo

2. Components

components/
├── cv/
│   ├── CVUpload.tsx                  // Drag-and-drop upload
│   └── CVAnalysisDisplay.tsx         // Display parsed CV
├── performance/
│   ├── PerformanceDashboard.tsx      // Radar chart, scores
│   └── InterviewHistory.tsx          // Timeline view
├── code-editor/
│   └── CodeEditor.tsx                // Monaco + test runner
├── common/
│   └── PDFExport.tsx                 // PDF generation utility
└── VoiceInterview.tsx                // WebSocket voice UI

3. Features by Component

CVUpload:

Drag-and-drop interface
File type validation (PDF, DOCX, TXT)
Upload progress
Error handling
Preview uploaded file

CVAnalysisDisplay:

Personal info (name, email, phone)
Skills as tags
Experience timeline
Education history
Edit mode
Industry categorization

PerformanceDashboard:

Radar chart (5 metrics)
Overall score card
Detailed score bars
Strengths list
Improvements list
Recommendation badge
PDF export button
Metadata (date, duration)

CodeEditor:

Monaco editor (VS Code)
Syntax highlighting
Run tests button
Test results display
Quality metrics
Save/Reset
Multi-language support

Backend Services

1. API Routers

routers/
├── sessions.py                       # Session management
│   ├── POST   /api/sessions/create
│   └── GET    /api/sessions/list
│
├── interviews.py                     # Interview operations
│   ├── GET    /api/interviews/{id}/transcript
│   ├── POST   /api/interviews/{id}/upload-cv
│   ├── GET    /api/interviews/{id}/cv-analysis
│   ├── POST   /api/interviews/{id}/end
│   └── GET    /api/interviews/{id}/performance-report
│
├── code.py                           # Code execution
│   ├── POST   /api/code/execute
│   ├── GET    /api/code/{id}/submissions
│   ├── GET    /api/code/{id}/submissions/{sub_id}
│   └── GET    /api/code/{id}/quality-summary
│
├── analytics.py                      # Performance analytics
│   ├── GET    /api/analytics/aggregate
│   ├── GET    /api/analytics/benchmarks/{type}
│   ├── GET    /api/analytics/trends?days=30
│   └── GET    /api/analytics/candidate/{name}/history
│
└── websocket.py                      # Real-time voice
    └── WS     /ws/interview/{id}

2. Service Layer

services/
├── bedrock_service.py                # Bedrock Agent integration
│   ├── invoke_agent()                # Streaming invocation
│   ├── initialize_session()          # Setup session state
│   └── extract_text_from_stream()    # Parse response
│
├── lambda_service.py                 # Direct Lambda calls
│   ├── invoke_code_executor()
│   ├── invoke_cv_analyzer()
│   └── invoke_performance_evaluator()
│
├── s3_service.py                     # S3 operations
│   ├── save_session()
│   ├── get_session()
│   ├── update_session_transcript()
│   ├── upload_cv()
│   └── list_all_sessions()
│
└── textract_service.py               # Document parsing
    ├── extract_text_from_pdf()
    ├── extract_text_from_multi_page_pdf()
    ├── extract_structured_data()
    └── IndustrySkillExtractor (class)

3. Data Models

models/
├── session.py                        # Session models
│   ├── TranscriptMessage
│   ├── TranscriptResponse
│   └── EndSessionResponse
│
└── code_submission.py                # Code tracking
    ├── TestCaseResult
    ├── CodeQualityMetrics
    ├── CodeSubmission
    └── CodeSubmissionTracker (class)

AWS Lambda Functions

1. Code Executor

Function: prepai-code-executor
Runtime: Python 3.11
Timeout: 30s
Memory: 512 MB

Purpose: Execute candidate code in sandboxed environment

Input:
{
  "code": "def solution(arr): return sorted(arr)",
  "language": "python",
  "testCases": [{"input": "[3,1,2]", "expected": "[1,2,3]"}],
  "functionName": "solution"
}

Output:
{
  "success": true,
  "testResults": [...],
  "allTestsPassed": true,
  "executionTime": 0.023
}

Features:
- Sandboxed execution (RestrictedPython)
- Multi-language (Python, JavaScript)
- Test case validation
- Timeout protection (5s max)
- Error handling

2. CV Analyzer

Function: prepai-cv-analyzer
Runtime: Python 3.11
Timeout: 30s
Memory: 512 MB

Purpose: Extract structured information from resumes

Input:
{
  "cvText": "John Doe\njohn@example.com\n...",
  "extractSkills": true
}

Output:
{
  "candidateName": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "skills": ["Python", "AWS", "React"],
  "experience": [...],
  "education": [...],
  "totalYearsExperience": 5.5
}

Features:
- Contact info extraction
- Skills detection (70+ keywords)
- Experience parsing
- Education extraction
- Years calculation

3. Performance Evaluator

Function: prepai-performance-evaluator
Runtime: Python 3.11
Timeout: 30s
Memory: 512 MB

Purpose: Generate comprehensive interview reports

Input:
{
  "sessionId": "session-123",
  "conversationHistory": [...],
  "codeSubmissions": [...],
  "interviewType": "Google SDE",
  "duration": 1800
}

Output:
{
  "overallScore": 7.8,
  "scores": {
    "technicalKnowledge": 8.5,
    "problemSolving": 7.5,
    "communication": 8.0,
    "codeQuality": 7.2,
    "culturalFit": 7.8
  },
  "strengths": [...],
  "improvements": [...],
  "recommendation": "HIRE"
}

Scoring Algorithm:
- Technical: correctness, depth, best practices
- Problem Solving: approach, optimization
- Communication: clarity, responsiveness
- Code Quality: style, tests, complexity
- Cultural Fit: behavioral indicators

Weighted Average: (30% + 25% + 20% + 15% + 10%)

Data Flow

1. Interview Session Flow

User Creates Session
        ↓
POST /api/sessions/create
        ↓
{
  interview_type: "Google SDE",
  candidate_name: "John Doe"
}
        ↓
Generate session_id (UUID)
        ↓
Save to S3: sessions/{session_id}.json
        ↓
Return session_id to frontend
        ↓
Navigate to /interview/new?type=...&name=...
        ↓
Initialize WebSocket: /ws/interview/{session_id}
        ↓
WebSocket Connected - Ready for voice

2. Voice Interview Flow

User Speaks (microphone)
        ↓
Browser captures audio (MediaRecorder)
        ↓
Send audio chunks via WebSocket
        ↓
Backend: Whisper STT
        ↓
Text transcript → Send to frontend
        ↓
Invoke Bedrock Agent (streaming)
        ↓
Agent decides:
  - Use Knowledge Base?
  - Call Code Executor?
  - Call CV Analyzer?
  - Call Performance Evaluator?
        ↓
Agent response (streaming text)
        ↓
Frontend displays text chunks
        ↓
Backend: Coqui TTS (sentence by sentence)
        ↓
Send audio chunks to frontend
        ↓
Browser plays audio
        ↓
Save transcript to S3

3. Code Execution Flow

User writes code in Monaco Editor
        ↓
Clicks "Run Tests"
        ↓
POST /api/code/execute
        ↓
{
  sessionId, code, language, testCases
}
        ↓
Backend: LambdaService.invoke_code_executor()
        ↓
Lambda executes code in sandbox
        ↓
Returns test results + execution time
        ↓
Backend: Calculate quality metrics
  - Lines of code
  - Cyclomatic complexity
  - Comments ratio
  - Quality score (0-10)
        ↓
Save CodeSubmission to session
        ↓
Return results + metrics to frontend
        ↓
Display test results (pass/fail)
        ↓
Show quality metrics

4. CV Upload & Analysis Flow

User uploads CV (PDF/DOCX/TXT)
        ↓
POST /api/interviews/{session_id}/upload-cv
        ↓
Backend reads file bytes
        ↓
Detect file type (.pdf, .docx, .txt)
        ↓
If PDF/DOCX:
  TextractService.extract_text_from_pdf()
    ↓
  AWS Textract API call
    ↓
  Extract text, forms, tables
    ↓
  Fallback to PyPDF2 if Textract fails
        ↓
Extract industry-specific skills
  - Software Engineering
  - Cloud Architecture
  - Data Science
        ↓
LambdaService.invoke_cv_analyzer()
        ↓
Lambda parses:
  - Name, email, phone
  - Skills (70+ keywords)
  - Experience
  - Education
        ↓
Merge results:
  - Basic analysis
  - Categorized skills
  - Industry match
        ↓
Save to session: cv_analysis
        ↓
Return enhanced analysis to frontend
        ↓
Display in CVAnalysisDisplay component

5. Performance Report Generation

User clicks "End Interview"
        ↓
POST /api/interviews/{session_id}/end
        ↓
Fetch session data from S3
        ↓
Calculate duration
        ↓
Gather data:
  - Conversation history
  - Code submissions
  - Interview type
        ↓
LambdaService.invoke_performance_evaluator()
        ↓
Lambda analyzes:
  1. Technical responses (keywords, depth)
  2. Problem solving (approach, code quality)
  3. Communication (clarity, length)
  4. Code quality (submissions)
  5. Cultural fit (behavioral indicators)
        ↓
Calculate weighted score:
  - Technical: 30%
  - Problem Solving: 25%
  - Communication: 20%
  - Code Quality: 15%
  - Cultural Fit: 10%
        ↓
Generate:
  - Overall score
  - Detailed scores
  - Strengths list
  - Improvements list
  - Recommendation (STRONG_HIRE, HIRE, etc.)
  - Detailed feedback
        ↓
Save report to S3: reports/{session_id}/
        ↓
Save report in session data
        ↓
Return report to frontend
        ↓
Display in PerformanceDashboard

6. Analytics Flow

GET /api/analytics/aggregate
        ↓
S3Service.list_all_sessions()
        ↓
Iterate through all sessions
        ↓
Calculate:
  - Total interviews
  - Completion rate
  - Average score
  - Interview type distribution
  - Recommendation distribution
        ↓
Return aggregated statistics
        ↓
─────────────────────────────────
GET /api/analytics/benchmarks/{type}
        ↓
Filter sessions by interview type
        ↓
Extract all scores
        ↓
Calculate percentiles:
  - P25, P50, P75, P90
  - Min, Max, Average
        ↓
For each metric (technical, problem solving, etc.)
        ↓
Return benchmark data
        ↓
─────────────────────────────────
GET /api/analytics/trends?days=30
        ↓
Filter sessions by date range
        ↓
Group by date
        ↓
Calculate daily averages
        ↓
Detect trend (improving/declining/stable)
        ↓
Return time series data

API Reference

Complete Endpoint List

Session Management

POST /api/sessions/create
Body: { interview_type, candidate_name }
Response: { session_id, created_at, ... }

GET /api/sessions/list
Response: { sessions: [...] }

Interview Operations

GET /api/interviews/{session_id}/transcript
Response: { session_id, transcript: [...] }

POST /api/interviews/{session_id}/upload-cv
Body: FormData (file)
Response: { success, analysis, message }

GET /api/interviews/{session_id}/cv-analysis
Response: { success, analysis, filename }

POST /api/interviews/{session_id}/end
Response: { session_id, status, report_url }

GET /api/interviews/{session_id}/performance-report
Response: { success, report, report_url }

Code Execution

POST /api/code/execute
Body: { sessionId, code, language, testCases, functionName }
Response: { success, testResults, qualityMetrics, ... }

GET /api/code/{session_id}/submissions
Response: { submissions, summary }

GET /api/code/{session_id}/submissions/{submission_id}
Response: { submission }

GET /api/code/{session_id}/quality-summary
Response: { averageQualityScore, averageComplexity, ... }

Analytics

GET /api/analytics/aggregate
Response: { total_interviews, average_score, ... }

GET /api/analytics/benchmarks/{interview_type}
Response: { benchmarks: { overall, technical, ... } }

GET /api/analytics/trends?days=30
Response: { trend, change, data: [...] }

GET /api/analytics/candidate/{name}/history
Response: { total_interviews, scores_over_time, ... }

WebSocket

WS /ws/interview/{session_id}

Messages:
  Client → Server:
    - { type: "speech_start" }
    - { type: "speech_end" }
    - Binary audio data

  Server → Client:
    - { type: "transcript", text, role, is_final }
    - { type: "llm_chunk", text }
    - { type: "assistant_complete", text, role }
    - { type: "error", message }
    - Binary audio data

Infrastructure

AWS Resources

S3 Bucket Structure

s3://prepai-user-data/
├── sessions/
│   ├── {session-id-1}.json
│   ├── {session-id-2}.json
│   └── ...
├── cvs/
│   ├── {session-id}/
│   │   ├── resume.pdf
│   │   └── cover-letter.pdf
│   └── ...
├── reports/
│   ├── {session-id}/
│   │   └── performance_report.json
│   └── ...
└── recordings/
    ├── {session-id}/
    │   ├── audio_20251017_120000.wav
    │   └── ...
    └── ...

Lambda Functions

Stack: prepai-lambda (SAM/CloudFormation)

Functions:
  - prepai-code-executor
  - prepai-cv-analyzer
  - prepai-performance-evaluator

Shared IAM Role: prepai-lambda-tools-role
Permissions:
  - CloudWatch Logs
  - S3 (prepai-user-data)
  - Textract (optional)

Timeout: 30 seconds
Memory: 512 MB
Runtime: Python 3.11

Bedrock Resources

Agent:
  Name: PrepAI Interview Agent
  Model: Claude 3 Haiku
  Streaming: Enabled

Knowledge Base:
  Name: PrepAI Interview Questions
  Type: RAG (Retrieval Augmented Generation)
  Embeddings: Titan Embeddings
  Vector Store: OpenSearch Serverless

Action Groups:
  1. CodeExecutor
     - execute-code
  2. CVAnalyzer
     - analyze-cv
  3. PerformanceEvaluator
     - evaluate-performance

IAM Policies

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockAgentAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeAgent",
        "bedrock:Retrieve",
        "bedrock:InvokeModel"
      ],
      "Resource": "*"
    },
    {
      "Sid": "LambdaInvoke",
      "Effect": "Allow",
      "Action": ["lambda:InvokeFunction"],
      "Resource": [
        "arn:aws:lambda:*:*:function:prepai-*"
      ]
    },
    {
      "Sid": "S3Access",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::prepai-user-data",
        "arn:aws:s3:::prepai-user-data/*"
      ]
    },
    {
      "Sid": "TextractAccess",
      "Effect": "Allow",
      "Action": [
        "textract:DetectDocumentText",
        "textract:AnalyzeDocument"
      ],
      "Resource": "*"
    }
  ]
}

Security

Authentication & Authorization

Current: None (Development)

Production Requirements:

JWT tokens for API authentication
OAuth 2.0 for user login
Session-based authentication
Role-based access control (RBAC)

Data Security

In Transit:

HTTPS/TLS for all API calls
WSS (WebSocket Secure) for voice
AWS SDK encrypted connections

At Rest:

S3 Server-Side Encryption (SSE-S3)
Lambda environment variables encryption
Bedrock agent data encryption

API Security

Rate Limiting: Not implemented (add in production) CORS: Enabled for localhost:3000, 3001 Input Validation: Pydantic models SQL Injection: N/A (no SQL database) XSS Protection: React auto-escapes CSRF: Not needed (stateless API)

Privacy

User data stored in S3 (encrypted)
No third-party analytics (GDPR compliant)
Audio recordings optional
Can delete sessions on request

Performance

Latency Benchmarks

API Endpoints:
  - Session Create: ~100-200ms
  - Session List: ~200-500ms (depends on count)
  - Upload CV: ~1-3s (Textract + analysis)
  - Execute Code: ~500-2000ms (Lambda cold start)
  - Performance Report: ~800-1500ms
  - Analytics Aggregate: ~300-800ms

WebSocket:
  - Connection: ~100-300ms
  - Speech-to-Text: ~500-1500ms (Whisper)
  - Bedrock Agent (first token): ~500-800ms
  - Text-to-Speech: ~200-800ms per sentence
  - Full voice turn: ~2-5 seconds

Lambda Functions:
  - Cold Start: ~1-2 seconds
  - Warm Start: ~100-300ms
  - Code Execution: ~50-500ms (code dependent)

Frontend:
  - Initial Load: ~1-2s
  - Monaco Editor Load: ~500-1000ms
  - Chart Rendering: ~100-300ms

Optimization Strategies

Backend:

Connection pooling (boto3)
Lambda warming (keep warm)
S3 caching (CloudFront CDN)
Gzip compression
Async operations

Frontend:

Code splitting (Next.js)
Image optimization
Lazy loading
React memoization
Component-level caching

AWS:

Provisioned concurrency (Lambda)
S3 Transfer Acceleration
CloudFront CDN
Multi-region deployment

Scalability

Current Limits:

Concurrent WebSockets: ~100 (FastAPI)
Lambda invocations: 1000/second (AWS default)
Bedrock Agent calls: Throttled by AWS
S3 requests: Unlimited

Production Scaling:

Load balancer (ALB)
Auto-scaling groups
Redis cache layer
Database (RDS/DynamoDB)
Multi-region deployment

Deployment

Development Setup

# Frontend
cd frontend
npm install
npm run dev
# http://localhost:3000

# Backend
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload
# http://localhost:8000

# Lambda Functions
cd lambda-tools
sam build
sam deploy --guided

Environment Variables

Frontend (.env.local):

NEXT_PUBLIC_API_URL=http://localhost:8000

Backend (.env):

# AWS
AWS_REGION=us-east-1
AWS_ACCESS_KEY=AKIA...
AWS_SECRET_ACCESS_KEY=...

# Bedrock
BEDROCK_AGENT_ID=ABCD1234
BEDROCK_AGENT_ALIAS_ID=TSTALIASID

# S3
S3_BUCKET_USER_DATA=prepai-user-data

Production Deployment

Frontend (Vercel/AWS Amplify)

# Build
npm run build

# Deploy to Vercel
vercel deploy --prod

# Or AWS Amplify
amplify init
amplify add hosting
amplify publish

Backend (AWS ECS/Lambda)

# Docker build
docker build -t prepai-backend .

# Push to ECR
aws ecr get-login-password | docker login ...
docker tag prepai-backend:latest ECR_URI
docker push ECR_URI

# Deploy to ECS
aws ecs update-service --service prepai-backend --force-new-deployment

Lambda Functions (SAM)

cd lambda-tools
sam build
sam deploy --stack-name prepai-lambda --capabilities CAPABILITY_NAMED_IAM

Monitoring

Recommended Tools:

CloudWatch Logs (Lambda, API)
CloudWatch Metrics (latency, errors)
AWS X-Ray (distributed tracing)
Sentry (error tracking)
DataDog (APM)

Cost Estimate

Monthly Costs (100 interviews)

AWS Services:
  Lambda Invocations:
    - Code Executor: 200 × $0.20/1M = $0.04
    - CV Analyzer: 100 × $0.20/1M = $0.02
    - Performance: 100 × $0.20/1M = $0.02
    Total: $0.08

  Bedrock Agent:
    - Haiku 3.5 Model: $0.80/1M input, $4/1M output
    - Avg conversation: 5k input, 2k output
    - 100 interviews × (5k + 2k) × $0.80 = $5.60
    Total: ~$6

  Textract:
    - $1.50/1000 pages
    - 100 CVs × 2 pages = 200 pages
    - 200 × $1.50/1000 = $0.30
    Total: $0.30

  S3 Storage:
    - Sessions: 100 × 100KB = 10MB
    - CVs: 100 × 1MB = 100MB
    - Reports: 100 × 50KB = 5MB
    - Total: 115MB × $0.023/GB = $0.003
    Total: ~$0.01

  Data Transfer:
    - Voice audio: 100 × 10MB = 1GB
    - $0.09/GB = $0.09
    Total: $0.09

Total AWS: ~$6.50/month

Hosting:
  - Vercel (Frontend): $20/month
  - AWS ECS (Backend): $30/month (Fargate)
  Total: $50/month

Grand Total: ~$56.50/month (100 interviews)
Per Interview: ~$0.57

Scaling Costs

1,000 interviews/month: ~$200
10,000 interviews/month: ~$1,500
100,000 interviews/month: ~$12,000

Major cost drivers:
1. Bedrock Agent API calls (70%)
2. Hosting/Compute (20%)
3. Textract (8%)
4. Other AWS services (2%)

Development Roadmap

Phase 1: Core Platform ✅

Next.js frontend
FastAPI backend
Basic session management

Phase 2: AI Integration ✅

Bedrock Agent setup
Knowledge Base (RAG)
Voice integration (STT/TTS)
WebSocket real-time

Phase 3: Lambda Tools ✅

Code Executor
CV Analyzer
Performance Evaluator
Action Groups

Phase 4: Advanced Features ✅

Code quality metrics
AWS Textract CV parsing
Industry-specific skills
Performance analytics
Benchmarking
Trend analysis

Phase 5: Production (In Progress)

Phase 6: Enhancements (Planned)

Troubleshooting

Common Issues

1. WebSocket Connection Failed

Error: WebSocket connection failed
Solution:
- Check backend is running (port 8000)
- Verify CORS settings
- Check firewall rules

2. Bedrock Agent Error

Error: Agent invocation failed
Solution:
- Verify BEDROCK_AGENT_ID in .env
- Check IAM permissions
- Ensure agent is prepared

3. Lambda Timeout

Error: Task timed out after 30 seconds
Solution:
- Increase timeout in template.yaml
- Optimize Lambda code
- Use provisioned concurrency

4. Textract Access Denied

Error: AccessDeniedException
Solution:
- Add textract:DetectDocumentText to IAM policy
- Verify AWS credentials

5. S3 Bucket Not Found

Error: NoSuchBucket
Solution:
- Create bucket: aws s3 mb s3://prepai-user-data
- Verify bucket name in .env

Contributing

Development Guidelines

Code Style:
- Frontend: ESLint + Prettier
- Backend: Black + Flake8
- Commit: Conventional Commits
Testing:
- Unit tests (Jest, Pytest)
- Integration tests
- E2E tests (Playwright)
Documentation:
- Update README
- Add JSDoc/docstrings
- Update architecture guide
Pull Requests:
- Feature branch workflow
- PR template
- Code review required

License

MIT License - See LICENSE file

Support

Documentation: /docs
Issues: GitHub Issues
Email: support@prepai.dev
Discord: discord.gg/prepai

Acknowledgments

AWS Bedrock Team
FastAPI Community
Next.js Team
Open Source Contributors

Last Updated: October 17, 2025 Version: 1.0.0 Status: Phase 4 Complete - Production Ready 🚀

FilesExpand file tree

ARCHITECTURE_GUIDE.md

Latest commit

History