|
<div class="docs-content" data-render>
|
|
# 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 # 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
|
|
agents/ autonomous maintenance fleet (developer tooling, off-limits)
|
|
```
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
python -c "from devplacepy.main import app" # must import clean
|
|
make validate # Python, JS, CSS, templates
|
|
```
|
|
|
|
Run the maintenance fleet over your changed files to catch style, duplication, and
|
|
documentation drift before review:
|
|
|
|
```bash
|
|
make maintenance # read-only report on changed files
|
|
make maintenance-fix # apply fixes to changed files
|
|
```
|
|
|
|
See [Running the agents](/docs/maintenance-usage.html) for the full fleet. 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.
|
|
- [Maintenance agents](/docs/maintenance-agents.html) - how the quality fleet keeps the
|
|
codebase consistent.
|
|
{% 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 %}
|
|
</div>
|