Skip to content

README.md

Latest commit

 

History

History
164 lines (124 loc) · 6.54 KB

README.md

File metadata and controls

164 lines (124 loc) · 6.54 KB

📁 Documentation

This folder contains all project documentation, architecture diagrams, and screenshots for the AI Tech Interview platform.

📂 Folder Structure

docs/
├── README.md (this file)
├── diagrams/
│   ├── architecture_flow.png
│   └── architecture_system.png
└── screenshots/
    ├── answer-recommendations.png
    ├── form-setup.png
    ├── interview-results.png
    ├── results-by-question.png
    └── score-breakdown.png

🗺️ Diagrams

Architecture Diagrams

Located in diagrams/

File Description Referenced In
architecture_system.png System Architecture - Shows the hybrid architecture with Next.js app connecting to Azure AI services (OpenAI, Speech). Illustrates the separation between frontend, backend APIs, and cloud services. README.md
architecture_flow.png Interview Flow - Visual representation of the voice-driven interview loop: question display → TTS playback → user recording → STT transcription → AI evaluation → results display. README.md

Diagram Details

architecture_system.png

  • Purpose: High-level system architecture
  • Components:
    • Next.js 16 Application (Server + Client Components)
    • Prisma 7 + PostgreSQL Database
    • Azure OpenAI Service (GPT-4o-mini)
    • Azure Speech Service (TTS + STT)
    • IndexedDB for offline storage
  • Key Patterns:
    • Server Components for data fetching
    • Client Components for interactivity
    • Token-based authentication for Azure services
    • Offline-first architecture with background sync

architecture_flow.png

  • Purpose: Interview process flow diagram
  • Stages:
    1. Session Setup: User inputs role, job description, seniority
    2. Topic Extraction: AI extracts key topics from job description
    3. Question Generation: AI generates role-specific questions
    4. Interview Loop:
      • Display question
      • TTS reads question aloud
      • User records response (with visible timer)
      • STT transcribes audio
      • Save response (online or offline)
    5. Evaluation: AI evaluates all responses
    6. Results Display: Show scores, feedback, improvements

📸 Screenshots

Located in screenshots/

File Description Features Shown
form-setup.png Session Setup Form - Initial form where users input their target role, company name, and job description. - Role title input
- Company name (optional)
- Job description textarea
- "Start Interview" CTA button
interview-results.png Interview Results Dashboard - Overview of all responses with overall score and performance band. - Overall score badge
- Performance band (Excellent/Good/Fair/Needs Improvement)
- Session metadata (role, seniority, date)
- List of all questions with individual scores
- Navigation to detailed feedback
results-by-question.png Question-by-Question Breakdown - Detailed view of responses for each interview question. - Question text display
- Transcription display
- Response duration
- Evaluation status indicator
score-breakdown.png Evaluation Score Breakdown - Visual breakdown of the 6 evaluation criteria with scores. - Relevance Score (25%)
- Technical Accuracy (25%)
- Clarity (20%)
- Depth (15%)
- Structure (10%)
- Confidence (5%)
- Overall score calculation
- Performance band
answer-recommendations.png Feedback & Recommendations - Detailed feedback section showing strengths, areas for improvement, and actionable suggestions. - Strengths list (✅ checkmarks)
- Improvements list (💡 icons)
- Specific suggestion for next steps
- Seniority-adjusted expectations
- Topic coverage analysis

Screenshot Guidelines

When adding new screenshots:

  1. Naming Convention: Use kebab-case (e.g., feature-name.png)
  2. Resolution: Minimum 1920x1080 for clarity
  3. Format: PNG with transparency where applicable
  4. Privacy: Redact any personal/sensitive information
  5. Update This File: Add entry to the table above with description

🖼️ Adding New Documentation

Adding Diagrams

  1. Create diagram using tools like:

    • Excalidraw (free, open-source)
    • Draw.io (free)
    • Mermaid (code-based, can be embedded in Markdown)
    • Figma, Lucidchart (if you have access)

  2. Export as PNG (recommended) or SVG

  3. Place in docs/diagrams/ with descriptive name

  4. Update this README with:

    • File name and description
    • What components/flows it shows
    • Where it's referenced in main docs

Adding Screenshots

  1. Take screenshot of feature/UI
  2. Crop to focus on relevant area
  3. Resize if needed (max 2000px width)
  4. Save as PNG in docs/screenshots/
  5. Update this README with:
    • File name and description
    • Features/components visible
    • Context for when this screen appears

🔗 Related Documentation

🤝 Contributing to Documentation

Documentation Standards

  1. Clarity: Write for developers unfamiliar with the project
  2. Completeness: Include all necessary context and prerequisites
  3. Currency: Update docs when features change
  4. Visual Aids: Use diagrams/screenshots to illustrate complex concepts
  5. Examples: Provide code snippets where applicable

Documentation Checklist

When adding a new feature:

  • Update main README with feature description
  • Add architecture diagram if introducing new components
  • Add screenshots showing UI changes
  • Update API reference if new endpoints added
  • Update LESSONS_LEARNED.md with technical challenges
  • Update this file with new diagram/screenshot entries

📝 Maintenance

Regular Updates Needed

  • Screenshots: When UI/UX changes
  • Architecture diagrams: When adding/removing services or major refactoring
  • Flow diagrams: When interview process changes

Document Review Schedule

  • After each major feature: Review and update relevant docs
  • Before releases: Ensure all docs reflect current state
  • Quarterly: Review for outdated information or broken links