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 and the
API reference 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:

make install      # pip install -e .
make dev          # uvicorn --reload on port 10500

Open http://localhost:10500. The first account you register becomes the administrator.
make prod runs the two-worker production server 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.py      SQLite via dataset; query and batch helpers
  models.py        Pydantic Form models   schemas.py  *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 AGENTS.md.

Validate before you finish

Never declare work done with a broken import or a validation error:

python -c "from devplacepy.main import app"   # must import clean
hawk .                                         # Python, JS, CSS, templates

Tests live in
tests/ and run with make test-unit, make test-api, and make test-e2e.

Read next