Repository Guidelines

Project Structure & Module Organization

backend/ contains FastAPI and worker code. Main logic is in backend/app/: routes in api/, business logic in services/, persistence in db/ and models/, and jobs in worker/.
frontend/ is a Vite + React + TypeScript app with UI code in frontend/src/ (components/, lib/api.ts, types.ts, styles).
doc/ stores project documentation, with doc/README.md as the entrypoint.
docker-compose.yml defines API, worker, frontend, Postgres, Redis, and Typesense. Runtime data is persisted in ./data/.

Build, Test, and Development Commands

Docker workflow (required):

multipass shell dcm-dev - enter the Linux VM used for Docker.
cd ~/dcm - move to the project directory inside the VM.
docker compose up --build -d - build and start all services.
docker compose down - stop and remove containers.
docker compose logs -f - stream logs across services.
DCM_DATA_DIR=/data docker compose up --build -d - override host data directory.
exit - leave the VM after Docker operations.

Frontend-only workflow:

cd frontend && npm run dev - start Vite dev server.
cd frontend && npm run build - run TypeScript checks and build production assets.
cd frontend && npm run preview - serve built frontend locally.

Coding Style & Naming Conventions

Follow existing module boundaries; keep files focused.
Python style in backend/: 4-space indentation, type hints, and docstrings for modules and functions; use snake_case for functions/modules and PascalCase for classes.
TypeScript style in frontend/: strict compiler settings (strict, noFallthroughCasesInSwitch, ES2022 target). Use PascalCase for React components (DocumentCard.tsx) and camelCase for variables/functions.

Testing Guidelines

This repository currently has no committed automated test suite. For each change, run the stack and validate impacted API/UI flows manually. Verify:

API health at GET /api/v1/health
document upload and search behavior in the frontend
service logs for processing failures (docker compose logs -f inside the VM)

When introducing automated tests, place them near the relevant module and document execution commands in README.md. Use test_*.py naming for backend tests and *.test.tsx for frontend tests.

Commit & Pull Request Guidelines

Git history is not available in this workspace snapshot, so no local message pattern can be inferred. Use concise, imperative commit subjects scoped to one change.
PRs should include:

what changed and why
linked issue/task ID
manual verification steps and outcomes
screenshots or short recordings for UI changes

2.7 KiB Raw Blame History