forked from retoor/devplacepy
retoorandClaude Sonnet 5
572e022584
Notifications: a new "thread" type notifies every other commenter on a
post whenever anyone comments on it, disregarding reply hierarchy -
excluding the actor and whoever already got a comment/reply
notification for that same event, so no one is double-notified.
Implemented via a background-deferred fan-out mirroring the existing
mention-notification pattern.
SEO: discussion_forum_posting() now embeds up to 20 of a post's
comments as nested schema.org Comment entities (not just an aggregate
count), and a new /topics hub plus /topics/{topic} pages give the
feed's topic filter real, independently crawlable/indexable URLs -
/feed?topic=X was never indexable since its canonical strips the
query string back to bare /feed. Both are wired end to end (schemas,
Devii actions, docs API, sitemap, locustfile load-test coverage).
Quiz player: the auto-advance to the next question used to hide the
just-answered slide in the same tick as rendering the grade, so on
any multi-question quiz the Correct/Not correct feedback was never
actually visible before the view moved on. Delayed via setTimeout,
with the pending timer cleared on manual navigation and on
disconnect so it can't race or fire on a removed component.
Also includes other local changes already in progress in this
working tree before this session (messaging, push delivery,
deepsearch jobs, game economy, quiz builder) - verified by the full
suite passing (3467 tests) but not authored or individually reviewed
in this session.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VL9Xn57W5UR3HZbbuuzxdK
77 lines
3.2 KiB
HTML
77 lines
3.2 KiB
HTML
<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 # 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 %}
|
|
</div>
|