HireMinds Documentation Plan¶
1. Documentation Categories & Priority¶
| Category | Description | Target Audience | Priority |
|---|---|---|---|
| Overview & Getting Started | High-level product summary and practical quick starts | All Users | P0 |
| Core Concepts | Terminology, roles, and lifecycles | All Users | P0 |
| ATS | Jobs, Applications, Candidates, Resume Processing | Recruiters, Hiring Managers | P0 |
| AI Interview System | Session lifecycle, scoring, voice pipelines, proctoring | Recruiters, Candidates | P0 |
| Role-Based Guides | End-to-end workflows per user persona | Specific Roles | P1 |
| Architecture | Technical breakdown (Frontend, Backend, AI, Data) | Developers, Architects | P1 |
| API Reference | Complete REST & WebSocket API specification | Developers, Integrators | P0 |
| Deployment & Ops | Local setup, environment config, CI/CD, Background Jobs | DevOps, Developers | P1 |
| Troubleshooting & FAQ | Issue resolution, logs, edge cases | All Users, DevOps | P2 |
2. Core Modules & Features Discovered¶
Implemented Features¶
- Auth: Email/password, OAuth (Google/LinkedIn), Role-based (Admin/Recruiter/Candidate), JWT.
- Jobs Management: Create, Edit, Publish, AI interview config, Question Banks.
- Candidate Management: Applications, Profile, Pipeline (Kanban).
- Resume Processing: Parsing via LLM, ATS semantic matching scoring via pgvector, AI Summary.
- AI Interviews (Voice):
- Primary: Low-latency WebRTC S2S Pipeline with client-side VAD
- Fallback: Legacy WebSocket/Deepgram Pipelines
- Lifecycle: Behavior -> Technical -> Coding
- Coding Tests: IDE, Code execution (sandbox), scoring.
- Proctoring: Tab-switching, face detection, trust score.
- GitHub Integration: Profile analysis, language breakdown, commit frequency, OSS contributions.
- Billing & Credits: Credit system, refunds on failure, cost metering.
- Analytics: Pipeline charts, AI vs Manual selection donuts.
- Background Jobs: Session Watchdog (sweeps stuck sessions).
Partial / Planned¶
- Assessments: Mentioned for Behavioral/Coding, but generic "Assessments" feature might be partial.
- Integrations: Only GitHub and Google/LinkedIn auth are currently fully realized in code. Job boards are planned.
3. User Roles¶
- Admin: User management, whitelist, role promotion.
- Recruiter: Create jobs, manage pipeline, review AI sessions, credit settings, view stats.
- Candidate: Apply to jobs (public or auth), take AI interviews, view application status.
4. API Inventory (High-level)¶
/api/v1/auth: login, register, sync, me/api/v1/jobs: CRUD, applications, public views/api/v1/applications: candidate views, status updates/api/v1/interviews: session lifecycle (create, chat, audio, end, schedule)/api/v1/ws: WebSocket signaling and live updates/api/v1/coding: runs sandbox tests/api/v1/proctoring: event aggregation/api/v1/reports,/api/v1/dashboard: analytics/api/v1/admin: user management
5. Background Processes¶
- APScheduler / Session Watchdog: Sweeps
IN_PROGRESS> 30min, refunds or scores.
6. Architecture & Data Model (ER)¶
- Next.js 14 Frontend -> FastAPI Backend -> PostgreSQL (pgvector).
- Supabase Auth. Redis caching.
- Models:
User,Job,Application,InterviewSession,Question,BehavioralTest,CodingTest,ProctoringEvent,LLMUsage,CreditUsage.
7. Next Steps¶
- Generate Information Architecture (Hierarchy).
- Write Overview, Core Concepts, Getting Started.
- Write Technical docs (Architecture, API, DB).
- Write Role guides and Ops docs.