mirror of
https://github.com/velocitatem/cvfs.git
synced 2026-05-31 16:53:38 +00:00
57 lines
2.9 KiB
Markdown
57 lines
2.9 KiB
Markdown
# Resume Branches Architecture
|
||
|
||
## Overview
|
||
|
||
Resume Branches treats a canonical ATS-safe DOCX as a source-of-truth document graph. The stack is split into a Next.js control plane, a FastAPI backend, and a Celery worker. MinIO hosts artifacts locally and can be swapped with any S3-compatible object storage in production.
|
||
|
||
## Services
|
||
|
||
- **apps/webapp** – Next.js 15 UI with a CV tree, upload workflow, specialization browser, and publish controls. It talks to the FastAPI backend via `NEXT_PUBLIC_API_BASE_URL`.
|
||
- **apps/backend/fastapi** – FastAPI service that handles ingest, structured patch storage, AI suggestions, and publishing. SQLAlchemy models persist into Postgres. Storage relies on MinIO.
|
||
- **apps/worker** – Celery worker for asynchronous DOCX parsing, keyword extraction, and optional AI tailoring loops. It consumes Redis as the broker backend.
|
||
- **dlib** – Shared domain library including: structured DOCX parsing (`dlib.cv`), patch validation, ATS guardrails, storage adapter (`dlib.storage`), MinIO client, and auth utilities.
|
||
|
||
## Data Model
|
||
|
||
- `cv_documents` – conceptual resume per owner.
|
||
- `cv_versions` – every branch or specialization. Stores structured block snapshots and artifact pointers.
|
||
- `cv_patches` – granular operations applied to a version.
|
||
- `submissions` – leaf nodes representing a company/role tailoring.
|
||
- `ai_suggestions` – AI proposals pending acceptance.
|
||
- `public_assets` – immutable artifacts for published CV links.
|
||
|
||
## Flows
|
||
|
||
1. **Upload canonical DOCX**: The backend stores the raw file in MinIO, parses the blocks, and seeds the root branch version.
|
||
2. **Create branches**: Provide a parent version + patch list. ATS guardrails enforce change budgets and ratio protections.
|
||
3. **Tailoring**: Submit job description + focus keywords. Suggestions are produced via `dlib.ai.tailoring` and saved for review.
|
||
4. **Publish**: Copy a version/submission artifact to a public slug (e.g., `https://cv.alves.world/cv/ml-engineer-stripe`).
|
||
|
||
## Environment Variables
|
||
|
||
- `DATABASE_URL` – Async SQLAlchemy DSN (default local Postgres).
|
||
- `MINIO_*` – Access, bucket, region, and endpoint for the object storage.
|
||
- `PUBLIC_BASE_URL` / `CV_PUBLIC_DOMAIN` – Hostnames for publishable resumes.
|
||
- `AUTH_*` – Optional OIDC issuer/audience. Disabled by default for local dev.
|
||
- `NEXT_PUBLIC_API_BASE_URL` – Next.js uses this to call FastAPI.
|
||
|
||
## Local Dev
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
make init
|
||
make dev # Next.js
|
||
make run.backend # FastAPI API server
|
||
make run.worker # Celery worker
|
||
make lift.database # Postgres profile
|
||
make lift.minio # MinIO bucket
|
||
```
|
||
|
||
## Dokploy Targets
|
||
|
||
- Backend (FastAPI) – build from `docker/backend-fastapi.Dockerfile`, run behind `api.cv.alves.world`.
|
||
- Webapp (Next.js) – build from `docker/webapp.Dockerfile`, exposed via `cv.alves.world`.
|
||
- Redis, Postgres, and MinIO run either inside Dokploy or via managed offerings.
|
||
|
||
See `docs/resume-branches/dokploy.md` for concrete API payloads.
|