Smart Interview Guideline

Your AI-powered interview preparation companion.

Smart Interview Guideline (S.I.G) helps IT professionals prepare for interviews using their target Job Description (JD). Get a personalized study roadmap, memory-scan quizzes, and self-check questions—all driven by AI and crowdsourced content.

---

Features

• JD-driven preparation — Paste or upload a Job Description; the system extracts skills and knowledge areas.
• 4-step flow — JD analysis → Memory Scan (micro-quiz) → Personalized Roadmap → Self-check questions.
• Personalized roadmap — Study plan adapted to your profile (role, experience) and time until the interview.
• Question bank — Memory scan and practice questions from a warehouse or AI-generated; supports multiple choice and knowledge-area tagging.
• Crowdsourcing — Contribute real interview questions; contributions can be linked to a preparation for context.
• Profile & CV — Set role, experience, preferred language; optional CV upload for better personalization.
• Admin — User management, contribution moderation, and usage oversight (separate admin login).

The UI is available in English and Vietnamese.

---

Tech Stack

Layer	Stack
Backend	Python 3.11+, FastAPI, SQLModel (async), PostgreSQL
Frontend	React 19, TypeScript, Vite, Redux Toolkit (RTK Query), Tailwind CSS
AI	OpenAI API (or compatible) for JD analysis, keyword extraction, and question/roadmap generation
Infra	Docker Compose (PostgreSQL, backend, frontend via nginx)

---

Prerequisites

• Docker Desktop 4.24+ (includes Docker Compose)
• Git

---

Quick Start

1. Clone and configure

git clone <repository-url>
cd smart-interview-guideline
cp .env.example .env

Edit .env and set at least:

• DATABASE_URL — PostgreSQL connection (default in Compose: postgresql://postgres:postgres@postgres:5432/smart_interview)
• OPENAI_API_KEY — Your OpenAI (or compatible) API key
• JWT_SECRET_KEY — A secret for JWT (change in production)

2. Run with Docker Compose

Production-style (backend + frontend build served by nginx):

docker compose up -d --build

• Frontend: http://localhost:8080
• Backend API: http://localhost:8000
• API docs: http://localhost:8000/docs

Development (Vite HMR + backend hot reload):

docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d
# Optional: sync + watch
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml watch

• Frontend (Vite): http://localhost:5173
• Backend: http://localhost:8000
• API docs: http://localhost:8000/docs

---

Configuration

Key environment variables (see .env.example for the full list):

Variable	Description
DATABASE_URL	PostgreSQL URL (async driver is used internally)
OPENAI_API_KEY	OpenAI (or compatible) API key
OPENAI_BASE_URL	Optional; for Azure or other OpenAI-compatible endpoints
JWT_SECRET_KEY	Secret for access/refresh tokens
CORS_ORIGINS	Allowed frontend origins (e.g. http://localhost:5173,http://localhost:8080)
VITE_API_BASE_URL	API base URL for the frontend build (e.g. http://localhost:8000/api or /api in production)

---

Project Structure

smart-interview-guideline/
├── app/                      # Backend (FastAPI)
│   ├── modules/               # Feature modules
│   │   ├── account/           # Auth, login, profile
│   │   ├── admin/             # Admin APIs
│   │   ├── analysis/          # JD analysis (extract keywords, create preparation)
│   │   ├── company/           # Companies (for contributions)
│   │   ├── contribution/      # Crowdsourced questions
│   │   ├── preparation/       # Preparation flow (JD → Memory Scan → Roadmap → Self-check)
│   │   ├── questions/         # Question bank, assessment
│   │   └── roadmap/           # Roadmap generation and daily tasks
│   ├── utils/                 # DB, auth, OpenAI client, etc.
│   ├── app.py                 # FastAPI app factory
│   └── config.py              # Pydantic settings
├── web/                       # Frontend (React + Vite)
│   ├── src/
│   │   ├── store/             # Redux store, RTK Query APIs
│   │   ├── pages/             # Route pages
│   │   ├── components/        # Shared UI
│   │   ├── layouts/           # App layouts
│   │   └── i18n/              # Locales (en, vi)
│   └── dist/                  # Production build (generated)
├── dockerfiles/               # Dockerfiles and nginx config
├── dev-docs/                  # SRS, user stories, design docs
├── docker-compose.yaml        # Production stack
├── docker-compose.dev.yaml    # Dev overrides (HMR, hot reload)
└── .env.example               # Example environment file

---

Development

• Backend: Edit ./app; Uvicorn reloads automatically in dev.
• Frontend: Edit ./web/src; Vite HMR updates the browser.
• New backend module: Add under app/modules/<name>/ with models.py, views.py, urls.py and register in app/app.py.
• Database: Tables are created on startup; for production migrations, consider Alembic.

See DEVELOPMENT.md for detailed workflow, database access, and troubleshooting.
See AGENTS.md for code style and conventions (for humans and AI agents).

---

API Documentation

When the backend is running, open:

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

---

Contributing

1. Fork the repository.
2. Create a branch from main for your change.
3. Follow the code style in AGENTS.md (Python: PEP 8, type hints, async; Frontend: TypeScript, React hooks, RTK Query).
4. Ensure the app runs with docker compose (and dev override when relevant).
5. Open a Pull Request with a short description of the change.

---

License

License terms are not yet defined. If you use or distribute this project, please check with the repository maintainers.

---

Related documentation

• DEVELOPMENT.md — Development setup, Docker, and troubleshooting
• AGENTS.md — Architecture, conventions, and notes for contributors
• dev-docs/mvp-srs.md — Product overview and requirements
• dev-docs/mvp-user-stories.md — User stories and acceptance criteria