Aimly

A career-intelligence web app that compares a resume against real market demand for a target job role, and returns a skill-gap analysis, a job-readiness score, and a personalized learning roadmap.

Aimly/
├── backend/    FastAPI + SQLAlchemy + Alembic (deterministic scoring; Groq for narrative only)
├── frontend/   Next.js + TypeScript + Tailwind (auth, dashboard, upload, reports, roadmap)
└── docker-compose.yml   Postgres + API + web, production-like

Docs: COMMANDS.md — every command by task · IMPLEMENTATION.md — full architecture, schema, and API reference.

Quickstart with Docker (Postgres + API + web)

cp .env.example .env          # set SECRET_KEY to a long random string
docker compose up --build

Then open http://localhost:3000. The API container runs database migrations automatically.

If ports 3000 / 8000 / 5432 are already in use, set FRONTEND_PORT, BACKEND_PORT, or POSTGRES_PORT in .env (container ports are unchanged).

For a real deployment, layer the production overlay on top — it forces ENV=production + COOKIE_SECURE=true, adds restart policies and a backend healthcheck, and assumes an HTTPS-terminating proxy in front:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up --build -d

Local dev (two terminals, no Docker)

Two terminals are needed — one for the backend, one for the frontend — since both need to stay running at the same time. Commands are listed in the exact order to run them. Pick the block matching your OS. The backend runs on SQLite with zero config; migrations apply automatically in dev.

---

Windows (PowerShell)

Terminal 1 — Backend

cd Aimly\backend
python -m venv venv
venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
uvicorn app.main:app --reload --port 8000

Terminal 2 — Frontend (open a new terminal, leave the backend running)

cd Aimly\frontend
npm install
Copy-Item .env.local.example .env.local
npm run dev

If venv\Scripts\Activate.ps1 is blocked by execution policy, run PowerShell as administrator once and execute Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, then retry.

---

Windows (Command Prompt / cmd.exe)

Terminal 1 — Backend

cd Aimly\backend
python -m venv venv
venv\Scripts\activate.bat
pip install -r requirements.txt
copy .env.example .env
uvicorn app.main:app --reload --port 8000

Terminal 2 — Frontend (open a new terminal, leave the backend running)

cd Aimly\frontend
npm install
copy .env.local.example .env.local
npm run dev

---

macOS / Linux (bash or zsh)

Terminal 1 — Backend

cd Aimly/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --port 8000

Terminal 2 — Frontend (open a new terminal, leave the backend running)

cd Aimly/frontend
npm install
cp .env.local.example .env.local
npm run dev

---

Then, on any OS

Open http://localhost:3000 in a browser, create an account, upload a resume (or paste its text), pick a target role, and you'll get a scored skill-gap report and a roadmap.

The backend's interactive API docs are available at http://localhost:8000/docs.

Before your first run, open backend/.env and set SECRET_KEY to any long random string — the placeholder value is fine for local testing but should never be used anywhere reachable outside your own machine. All other .env values (Groq, Adzuna, JSearch keys) are optional; the app runs fully offline without them.

On every run after the first, only the last command in each block (uvicorn ... / npm run dev) needs to be repeated — skip the venv creation, pip install, npm install, and .env copy steps once they've been done once.

Tests & migrations and every other command (Alembic, pytest, ruff, Docker, production) are in COMMANDS.md.

What's real

• Auth: signup / login / logout with httpOnly access + rotating refresh cookies, email verification, password reset over SMTP, rate limiting, account lockout, change password/email, account deletion, and a full data export.
• Analysis: resume parsing (PDF/DOCX/text), deterministic skill matching + scoring, roadmap ranking with hour estimates and calendar (.ics) export, "analyze against a pasted job description", role comparison, PDF report, cover-letter and LinkedIn drafts, mock interview questions, skill self-assessment quizzes, shareable read-only report links.
• Ops: Alembic migrations, Postgres support, Docker + docker-compose, GitHub Actions CI, structured logging with request IDs, health/readiness probes, optional Sentry, optional APScheduler email digests, pytest suite.

What's curated / optional

• Job-market data (backend/app/data/seed_data.py) is a hand-curated snapshot for 18 roles, standing in for the Adzuna/JSearch aggregation pipeline. Set ADZUNA_* / RAPIDAPI_KEY to pull live postings; otherwise the snapshot is used. Users can also define custom roles from a skill list.
• Groq generates narrative text (score explanations, roadmap notes, cover letters) only when GROQ_API_KEY is set; deterministic templates keep the app fully functional offline.
• SMTP is optional in dev — verification/reset emails are logged to the console when SMTP_HOST is unset.

See backend/backend-README.md and frontend/frontend-README.md for more detail on each half, and IMPLEMENTATION.md for the complete implementation reference.