45 lines
2.7 KiB
Markdown
45 lines
2.7 KiB
Markdown
# 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
|