# Getting started A single path from a fresh clone to a running instance and your first change. If you only want to call the API, jump to [Authentication](/docs/authentication.html) and the [API reference](/docs/conventions.html) instead - this page is for working on DevPlace itself. ## Run it locally DevPlace is a Python package. Install it editable, then start the reloading dev server: ```bash make install # create .venv if needed, pip install -e ".[dev]", playwright chromium make dev # uvicorn --reload on port 10500 ``` Open `http://localhost:10500`. The first account you register becomes the administrator. `make prod` runs the production server with one worker per CPU core on the same port. ## Repository layout ``` devplacepy/ the application package main.py mounts routers, middleware, startup/shutdown routers/ one directory per URL domain (mirrors the endpoint tree) templates/ Jinja2 pages; static/ holds CSS and ES6 modules database/ SQLite via dataset; query and batch helpers models.py Pydantic Form models schemas/ *Out JSON models services/ background + async-job services, Devii, containers tests/ unit / api / e2e, mirroring the route or source path ``` ## How a feature is shaped Every feature is **one data source with four faces**: the same route handler is rendered as HTML, served as JSON, called by the Devii assistant as a tool, and described in the API docs. The usual failure is changing one face and forgetting a connected one. Work in this order so nothing is dropped: 1. **Data** - query helpers in `database.py`, a `Form` model in `models.py`, an `*Out` model in `schemas.py`. 2. **Server** - the handler in `routers/`, with the right guard (`get_current_user` for public reads, `require_user`, `require_admin`); return both faces via `respond(request, template, ctx, model=XOut)`. 3. **View** - extend `base.html`; one ES6 class per file under `static/js/`. 4. **Agent and docs** - add a Devii tool when a user could ask for the action, an `endpoint()` entry in `docs_api.py`, and update `README.md` and the relevant nested `CLAUDE.md`. ## Validate before you finish Never declare work done with a broken import or a validation error: ```bash python -c "from devplacepy.main import app" # must import clean python -m py_compile <changed .py> # Python syntax python -m pyflakes <changed .py> # Python lint node --check <changed .js> # JavaScript ``` Changed stylesheets are checked for brace balance and changed templates for tag and `{% %}` balance. Tests live in `tests/` and run with `make test-unit`, `make test-api`, and `make test-e2e`. ## Read next - [Conventions and Errors](/docs/conventions.html) - the rules every endpoint shares. - [Components overview](/docs/components.html) and the [design system](/docs/styles.html) - the frontend building blocks and styling rules. {% if is_admin(user) %} - [Architecture overview](/docs/architecture.html) - the request pipeline, backend, and frontend in depth. - [Development workflow](/docs/architecture-workflow.html) and [Testing overview](/docs/testing.html) - the deeper contributor reference. {% endif %}