# Repository Guidelines

> This repo has two main apps: backend/ (FastAPI) and frontend/ (Next.js). Backend code lives in backend/app/ with feature areas like api/, services/, repositories/, rules/, and providers/.

- Skill: `tools-only/repository-guidelines-10` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/repository-guidelines-10`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/repository-guidelines-10/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/repository-guidelines-10

---

# Repository Guidelines

## Project Structure & Module Organization
This repo has two main apps: `backend/` (FastAPI) and `frontend/` (Next.js). Backend code lives in `backend/app/` with feature areas like `api/`, `services/`, `repositories/`, `rules/`, and `providers/`. Tests are in `backend/tests/` (unit and integration). Frontend source is in `frontend/src/` with routes under `src/app/`, reusable UI in `src/components/`, and API clients in `src/lib/api/`. Static assets live in `frontend/public/`. Architecture notes are in `docs/`.

## Build, Test, and Development Commands
Run commands from each app directory:

```bash
cd backend
uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
uv run python -m app.main
pytest
```

- `uv run python -m app.main`: start the API service (uses the configured FastAPI entrypoint).
- `pytest`: run backend unit/integration tests.

```bash
cd frontend
npm run dev
npm run build
npm run lint
```

- `npm run dev`: start the frontend dev server.
- `npm run build`: production build.
- `npm run lint`: ESLint checks.

## Local Setup & CI Expectations
Backend uses `uv` with a Python 3.12 virtualenv; install dependencies from `backend/requirements.txt`. Frontend uses npm (or pnpm/yarn if you prefer) with `frontend/package.json`.

CI is not defined in this repo, so treat local checks as the gate: run `pytest` for backend changes and `npm run lint` (plus `npm run build` when touching Next.js config) before opening a PR.

## Coding Style & Naming Conventions
Backend: 4-space indentation, `snake_case` for functions/variables, `PascalCase` for classes. Keep modules small and follow existing layering (`api/` -> `services/` -> `repositories/`). Frontend: TypeScript/React with `PascalCase` components (e.g., `LogList.tsx`), `camelCase` for hooks and utilities (e.g., `useProviders`). ESLint is the primary frontend style gate; no auto-formatter is configured.

## Testing Guidelines
Backend tests use `pytest` with files named `test_*.py` under `backend/tests/`. Add unit tests alongside the relevant module area (e.g., `backend/tests/unit/test_services/`). No frontend test framework is currently configured; keep UI changes manual-testable and note coverage gaps in PRs.

## Commit & Pull Request Guidelines
Recent commits use short, descriptive messages (often in Chinese) and sometimes include a tracker suffix like `(vibe-kanban <id>)`. Follow that style: keep messages brief and focused. PRs should include: a summary, test commands run, and screenshots for UI changes. Link related issues or kanban cards when available.

## Configuration & Security
Backend settings come from environment variables (see `backend/app/config.py`). Common ones include `DATABASE_TYPE` and `DATABASE_URL`; use a local `.env` and avoid committing secrets or API keys.