|
1 | | -# Repository Guidelines |
2 | | - |
3 | | -## Project Structure & Module Organization |
4 | | -Core application code lives in `src/`. Use `src/api/` for FastAPI routes, `src/services/` for orchestration and business logic, `src/services/sandbox/` and `src/services/container/` for execution backends, `src/models/` for request/response models, and `src/config/` for environment-driven settings. Supporting docs are in `docs/`, dashboard assets in `dashboard/`, container/runtime files in `docker/`, and helper scripts in `scripts/`. |
5 | | - |
6 | | -Tests are split by scope: `tests/unit/` for isolated service logic, `tests/integration/` for API and dependency-backed flows, `tests/functional/` for live endpoint testing, and `tests/snapshots/` for stored response fixtures. |
7 | | - |
8 | | -## Build, Test, and Development Commands |
9 | | -Set up a local environment with: |
10 | | - |
11 | | -```bash |
12 | | -python -m venv .venv |
13 | | -source .venv/bin/activate |
14 | | -pip install -r requirements.txt |
15 | | -cp .env.example .env |
16 | | -``` |
17 | | - |
18 | | -Run locally with `uvicorn src.main:app --reload`. Start required services with `docker compose up -d`, and build the sandbox image with `docker build -t code-interpreter:nsjail .`. |
19 | | - |
20 | | -Key verification commands: |
21 | | - |
22 | | -```bash |
23 | | -pytest tests/unit/ |
24 | | -pytest tests/integration/ |
25 | | -pytest tests/functional/ -v |
26 | | -pytest --cov=src tests/ |
27 | | -black src/ --check |
28 | | -flake8 src/ |
29 | | -mypy src/ |
30 | | -bandit -r src/ -s B104,B108 --severity-level high |
31 | | -``` |
32 | | - |
33 | | -## Coding Style & Naming Conventions |
34 | | -Target Python 3.11+ with 4-space indentation, explicit type hints, and small async-friendly service boundaries. Follow Black formatting and keep code Flake8- and MyPy-clean. Use `snake_case` for modules, functions, and variables; `PascalCase` for classes and Pydantic models; and `UPPER_SNAKE_CASE` for constants and env names. |
35 | | - |
36 | | -## Testing Guidelines |
37 | | -Pytest, `pytest-asyncio`, and `pytest-cov` are the standard tools. Name files `test_*.py` and mirror the component under test where practical, for example `tests/unit/test_session_service.py`. Add unit coverage for new logic first, then integration coverage for endpoint or storage changes. Functional tests use `API_BASE`, `API_KEY`, and `API_TIMEOUT`; keep them stable against a real running API. |
38 | | - |
39 | | -## Commit & Pull Request Guidelines |
40 | | -Recent history uses short imperative subjects with prefixes such as `fix:`, `docs:`, `chore(...)`, and `feat:`. Keep the first line under 72 characters and reference issues in the body when relevant. Pull requests should explain behavior changes, note config or API contract impacts, and include the commands you ran. Add screenshots when changing the admin dashboard or other visible UI. |
41 | | - |
42 | | -## Security & Configuration Tips |
43 | | -Never commit populated `.env` files, API keys, or storage credentials. Use `.env.example` as the template, and review `docs/CONFIGURATION.md` and `docs/SECURITY.md` before changing auth, sandboxing, Redis, or MinIO behavior. |
| 1 | +Read CLAUDE.md |
0 commit comments