Nautilus/ledgerdock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refresh local AGENTS guide

Browse Source
This commit is contained in:
Beda Schmid
2026-02-21 11:13:52 -03:00
parent 04cf830e21
commit d4298c337f
1 changed files with 22 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
AGENTS.md
View File

@@ -1,44 +1,28 @@
# Repository Guidelines # Repository Guidelines
## Project Structure & Module Organization ## Stack Snapshot
`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/`. - DMS monorepo with FastAPI API + RQ worker (`backend/`) and React + Vite + TypeScript frontend (`frontend/`).
`frontend/` is a Vite + React + TypeScript app with UI code in `frontend/src/` (`components/`, `lib/api.ts`, `types.ts`, styles). - Services in `docker-compose.yml`: `api`, `worker`, `frontend`, `db` (Postgres), `redis`, `typesense`.
`doc/` stores project documentation, with `doc/README.md` as the entrypoint. - Runtime persistence uses Docker named volumes (`db-data`, `redis-data`, `dcm-storage`, `typesense-data`).
`docker-compose.yml` defines API, worker, frontend, Postgres, Redis, and Typesense. Runtime data is persisted in `./data/`.
## Build, Test, and Development Commands ## Project Layout
Docker workflow (required): - Backend app code: `backend/app/` (`api/`, `services/`, `db/`, `models/`, `schemas/`, `worker/`).
- `multipass shell dcm-dev` - enter the Linux VM used for Docker. - Backend dependencies: `backend/requirements.txt`.
- `cd ~/dcm` - move to the project directory inside the VM. - Frontend app code: `frontend/src/` (`components/`, `lib/api.ts`, `types.ts`, styles).
- `docker compose up --build -d` - build and start all services. - Technical docs live in `doc/` with `doc/README.md` as the index.
- `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: ## Working Commands
- `cd frontend && npm run dev` - start Vite dev server. - Start full stack: `docker compose up --build -d`
- `cd frontend && npm run build` - run TypeScript checks and build production assets. - Stop stack: `docker compose down`
- `cd frontend && npm run preview` - serve built frontend locally. - Tail logs: `docker compose logs -f`
- Frontend dev only: `cd frontend && npm run dev`
- Frontend production build: `cd frontend && npm run build`
## Coding Style & Naming Conventions ## Validation
Follow existing module boundaries; keep files focused. - No automated test suite is currently committed.
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. - Manual checks for code changes: `GET /api/v1/health`, upload + processing flow, search, document preview/download, and clean `docker compose logs -f` output for `api` and `worker`.
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 ## If You Add Tests
This repository currently has no committed automated test suite. For each change, run the stack and validate impacted API/UI flows manually. Verify: - Backend: place near changed module, use `test_*.py`.
- API health at `GET /api/v1/health` - Frontend: use `*.test.tsx`.
- document upload and search behavior in the frontend - Update `README.md` and `doc/README.md` with test run commands.
- 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