Learn with hands-on validation — an adaptive skill graph that diagnoses, forges your roadmap live, validates mastery, and generates evidence for mentors.
Hackathon Borderless BASE 01/2026 · repository HB01-2026_soft-push (Soft Push)
Live app: forge.pedroalano.com.br · Watch the full E2E demo (video)
| Layer | Technology |
|---|---|
| Frontend | Next.js + TypeScript + Tailwind |
| Backend | FastAPI + Pydantic + SQLAlchemy |
| Database | PostgreSQL |
| AI | LangGraph + LangChain + LangSmith |
| Deploy (production) | GHCR + VPS (nginx + Docker Compose) |
Career Forge is an AI-native learning system for people transitioning into a tech career (often starting from scratch). Without AI, the core flow stops.
Problem: generic roadmaps don't know where you're starting from and don't validate whether you actually learned anything.
Solution: a personalized roadmap inspired by roadmap.sh, with an AI engine at every critical stage — diagnosis, live forge, interview-based validation, and roadmap adaptation.
Full product and architecture overview: docs/CHECKPOINT.md.
- Adaptive diagnosis (CTRR) — a multi-turn AI interview that maps where you actually start (≤2 questions per round, adaptive rubric).
- Live Roadmap Forge — the AI builds your personalized roadmap with visible reasoning, streamed live over SSE.
- AI mastery validation — interview-based validation; the roadmap reacts (unlocks/blocks nodes) to your result.
- Adaptive memory (knowledge gaps) — wrong answers become structured gaps that feed future mock interviews, the mentor, and remediation tasks.
- MCQ mock interview — agent-generated questions with deterministic, server-side scoring.
- Chapter Q&A tutor — a grounded tutor per roadmap node (key concepts + official references).
- Contextual mentor + evidence report — chat with full progress context and a mentor-facing evidence report.
- Goal — choose a target and motivation (+ optional PDF CV).
- Diagnosis interview (CTRR) — the AI asks up to 2 questions per round, with an adaptive rubric.
- Editable diagnosis — you adjust gaps and strengths before generating the roadmap.
- Live Roadmap Forge — streaming in timeline only mode (no graph preview during generation).
- Vertical roadmap (artifact mode) — post-forge steady state, vertical roadmap style.
- Validate with AI — mastery interview; the roadmap reacts to the result.
- Contextual mentor + report — chat with progress context and evidence for Borderless mentors.
apps/frontend/ Next.js (App Router: setup + artifact)
apps/backend/ FastAPI (career_forge)
data/roadmap.json Static skill catalog
PostgreSQL Profiles, roadmap, diagnosis sessions, graph_runs
Detailed structure: docs/engineering/REPO-STRUCTURE.md.
Diagrams (module dependencies + per-feature sequence, rendered on GitHub): docs/ARCHITECTURE.md.
- Docker + Docker Compose
- OpenAI API key (required for diagnosis, forge, and validation)
git clone https://github.com/ProgramadoresSemPatria/HB01-2026_soft-push.git
cd HB01-2026_soft-push
cp .env.example .env
# Edit .env and set OPENAI_API_KEY=sk-...
make up
make status # shows real URLs (frontend port comes from WEB_HOST_PORT in .env)
make smoke # validates harness + health checks| Service | Typical URL |
|---|---|
| Frontend | http://localhost:<WEB_HOST_PORT> (default in .env.example: 3300) |
| Backend (OpenAPI) | http://localhost:8000/docs |
| Health | http://localhost:8000/health |
Stop everything: make down
Frontend port: the value comes from
WEB_HOST_PORTin your.env.make statusprints the correct URL. If 3300 is already in use, pick another port (e.g.WEB_HOST_PORT=3000) and add the origin toCORS_ORIGINS.
Conflict on 5432: if another Postgres is already using port 5432 on the host, stop the other service or adjust the mapping in
docker-compose.ymlbeforemake up.
Copy .env.example to .env and fill in at least:
| Variable | Required | Use |
|---|---|---|
OPENAI_API_KEY |
Yes (AI) | Diagnosis, forge, validation, mock interview |
DATABASE_URL |
Yes (Docker fills it in) | Postgres |
CORS_ORIGINS |
Yes | Must include the frontend URL (http://localhost:3300, etc.) |
NEXT_PUBLIC_BACKEND_URL |
Yes | Frontend → API |
NEXT_PUBLIC_API_URL |
Yes | Same |
WEB_HOST_PORT |
Yes (local) | Published Next.js port on the host |
LANGSMITH_API_KEY |
No | LLM trace observability |
LANGSMITH_PROJECT |
No | LangSmith project (e.g. career-forge) |
VPS production: .env.production.example and docs/engineering/DEPLOY-VPS.md.
With the stack running (make up):
- Open the frontend (
make status→ URL). - Set your goal and motivation; optionally attach a CV.
- Complete the diagnosis interview (pills/text from the API).
- In editable diagnosis, adjust gaps and click Generate roadmap.
- Watch the Forge (SSE timeline) until the reveal → vertical roadmap.
- Open a node → Validate with AI → watch the score and the roadmap react.
- (Optional) Mentor / report on the roadmap.
Script aligned with docs/CHECKPOINT.md § Demo script.
| Command | Description |
|---|---|
make up |
Starts postgres + backend + frontend (builds if needed) |
make down |
Stops the stack |
make status |
Compose status + URLs |
make smoke |
Harness + health checks |
make test |
Bootstrap Postgres + Alembic upgrade + backend pytest |
make seed |
Seed the catalog + demo user Ana |
make agent-verify |
Structure Gate C + optional /health |
Useful for fine-grained backend debugging or running the frontend in isolation.
# Terminal 1 — Postgres only
docker compose up -d postgres
# Terminal 2 — Backend
cd apps/backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export DATABASE_URL=postgresql+psycopg://careerforge:careerforge@localhost:5432/careerforge
export OPENAI_API_KEY=sk-...
PYTHONPATH=src uvicorn career_forge.main:app --reload --port 8000
# Terminal 3 — Frontend (at the repo root, using the root .env)
cd apps/frontend
pnpm install && pnpm devMake sure CORS_ORIGINS and NEXT_PUBLIC_* in the root .env point to the port where Next starts.
| Environment | How |
|---|---|
| Current production | Live at forge.pedroalano.com.br · Images at ghcr.io/pedroalano/career-forge-{backend,frontend} · VPS + nginx + docker-compose.prod.yml |
| CI/CD | .github/workflows/deploy.yml (build/push + SSH deploy) |
Full runbook: docs/engineering/DEPLOY-VPS.md.
| For whom | Where to start |
|---|---|
| New to the project | docs/CHECKPOINT.md — complete overview |
| Architecture (diagrams) | docs/ARCHITECTURE.md — dependencies + per-feature sequence (Mermaid) |
| Docs index | docs/README.md |
| Agents / contributing | AGENTS.md · docs/ROADMAP.md · docs/STATUS.md |
| AI / LangGraph | docs/engineering/EXECUTION-FLOW.md |
| CTRR diagnosis | docs/product/DIAGNOSIS-INTERVIEW.md |
| Design / UI | claude-design-docs/ (prototype + tokens) |
Not the production app — it's for tokens and components:
cd claude-design-docs/prototype
python3 -m http.server 8765
# http://localhost:8765/| Symptom | Likely cause | What to do |
|---|---|---|
failed to fetch in the browser |
CORS or backend down | Check that CORS_ORIGINS includes the frontend URL; docker compose logs backend |
| Diagnosis/forge not responding | OPENAI_API_KEY empty |
Fill it in .env and make down && make up |
| Postgres won't start | Port 5432 in use | Free the port or adjust docker-compose.yml |
| Frontend on the wrong port | WEB_HOST_PORT |
Use make status and open the displayed URL |
Backend tests fail with connection refused on localhost:5432 |
Postgres wasn't running before pytest | Use make test (now starts postgres, waits for readiness, and runs alembic upgrade head) |
More recipes: .cursor/skills/local-debug/SKILL.md.
Programadores Sem Pátria — Hackathon BASE 2026
- Matheus Oliveira — AI / LangGraph: the AI engine across diagnosis (CTRR), live forge, validation, mentor & tutor, and adaptive knowledge-gap memory.
- Pedro Alano — Infrastructure & deploy + fullstack: Docker/Compose, GHCR + VPS pipeline (CI/CD), and across-the-stack work.
- Arthur Araujo — Frontend: Next.js UI, the live forge stream UX, and roadmap/validation screens.
Project developed during HB01-2026 (BASE Mentorship).