Voychev — Portfolio + AI Chat

Personal portfolio site for Boris Voychev: a React SPA, a FastAPI backend, and an agentic RAG chat assistant that answers questions about Boris's experience, blog, and source code. Runs locally on Docker; production is GCP / Cloud Run.

Live: boris.voychev.com · API at api.voychev.com

---

Start here

You want to…	Read
Understand the whole system	ARCHITECTURE.md
Run it locally	Quick start below, then voychev-deploy/README.md
Deploy / set up GCP infra	DEPLOYMENT.md
Understand the security posture	SECURITY.md
Understand the CI/CD pipeline	CICD.md
Run / understand the tests	TESTING.md
Work on the frontend	voychev/README.md + voychev/architecture/
Work on the backend	voychev-backend/README.md + voychev-backend/architecture/

---

The three subprojects

Directory	What	Stack
voychev/	Frontend SPA	React 19, TypeScript, Vite, Redux Toolkit, Material UI
voychev-backend/	API + AI chat	FastAPI, SQLModel/psycopg3, LangGraph, pgvector
voychev-deploy/	Local Docker stacks + GCP/Terraform infra	docker compose, nginx, Terraform, Cloud Run

Browser (React SPA)
   │ https
   ▼
boris.voychev.com ──► Cloud Run: frontend (nginx + dist/)
api.voychev.com   ──► Cloud Run: backend (FastAPI)
                          ├─► Cloud SQL Postgres 16 + pgvector
                          └─► OpenAI / Anthropic (chat + embeddings)

Full diagram and request-flow layering in ARCHITECTURE.md.

---

Quick start

Local dev stack (hot reload — Vite HMR + fastapi dev):

cd voychev-deploy
cp .env.example .env
# Edit .env: set POSTGRES_PASSWORD, JWT_SECRET, REINDEX_API_KEY
# (and OPENAI_API_KEY / ANTHROPIC_API_KEY for the chat feature)

docker compose up --build     # hot reload; source edits reload live
./scripts/seed.sh             # first time only, idempotent

App: http://localhost:5173

Backend-only, no database (JSON backend, fastest path for API work):

cd voychev-backend
uv sync
cp .env.example .env          # REPOSITORY_BACKEND=json is the default
uv run fastapi dev src/voychev_api/main.py    # http://localhost:8000/docs

Frontend-only against a running backend:

cd voychev
npm install
npm run dev                   # http://localhost:5173, proxies /api → :8000

See voychev-deploy/README.md for the prod-parity stack (nginx + TLS) and DEPLOYMENT.md for GCP.

---

Conventions

• Backend layering (router → service → repository, three-way DTO separation) and the decisions behind it: voychev-backend/architecture/ (ARCHITECTURE.md, DECISIONS.md).
• No secrets in git. Secrets come from .env* (gitignored) locally and GCP Secret Manager in production. CI runs gitleaks on every push/PR.
• Commits / deploy. Push to master runs the security workflow (tests + scans). Deploy is manual — once security is green, dispatch the deploy workflow (build → migrate → deploy). Chat reindex is also manual (admin button for portfolio; reindex-code.yml for code). See CICD.md.