Davide Scaini
a14cee8710
scripts/gen_graph.py parses FastAPI routes, frontend fetch() calls, component imports, and Python imports to auto-generate: - docs/architecture.mmd: Mermaid diagram with API/Pages/Components/Python subgraphs - docs/graph.html: standalone vis.js interactive graph (dark theme, group filters, search highlight, click-to-highlight connected nodes) docs-proposal.md: proposal for a docs/ folder structure, API documentation strategy, and tooling recommendations (plain markdown → MkDocs Material).
114 lines
4.6 KiB
Markdown
114 lines
4.6 KiB
Markdown
# Documentation proposal
|
|
|
|
## Problem
|
|
|
|
The project has no user-facing or developer-facing docs. Knowledge lives in `CLAUDE.md`
|
|
(written for AI context, not humans), scattered inline comments, and the code itself.
|
|
As the feature surface grows and more users join, we need:
|
|
|
|
- A guide for **users** (how to upload, sync, edit, manage privacy)
|
|
- A guide for **admins** (how to run an instance, manage users, reset passwords)
|
|
- An **API reference** (what endpoints exist, what they expect, what they return)
|
|
- A **developer guide** (how to run locally, architecture, how to contribute)
|
|
|
|
---
|
|
|
|
## Proposed structure
|
|
|
|
```
|
|
docs/
|
|
index.md Overview and quick links
|
|
user-guide.md End-user: upload, sync, edit, privacy, settings
|
|
admin-guide.md Admin: deploy, init, invite users, reset passwords, rebuild
|
|
api.md API reference (hand-written, augmented by OpenAPI)
|
|
architecture.md BAS schema, data flow, shard model, federation
|
|
developer-guide.md Local setup, how to run tests, how to contribute
|
|
```
|
|
|
|
`CLAUDE.md` stays as-is — it is AI context, not user docs. The two serve different
|
|
audiences and should not be merged.
|
|
|
|
---
|
|
|
|
## API documentation strategy
|
|
|
|
FastAPI auto-generates an OpenAPI 3.1 spec from the route decorators. It is already
|
|
served at `/api/docs` (Swagger UI) and `/api/redoc` (ReDoc) when the server is running.
|
|
Right now the auto-docs are sparse because:
|
|
|
|
- Most endpoints return bare `JSONResponse` instead of typed Pydantic response models
|
|
- Endpoint docstrings are minimal or absent
|
|
- Request bodies are raw `request.json()` instead of Pydantic models
|
|
|
|
### Recommended approach: two-layer docs
|
|
|
|
**Layer 1 — machine-readable (OpenAPI, auto-generated)**
|
|
|
|
Incrementally add Pydantic request/response models to the endpoints that matter most
|
|
(auth, activity CRUD, admin actions). FastAPI will pick them up automatically and the
|
|
Swagger UI becomes usable. No extra tooling needed.
|
|
|
|
Priority endpoints to type first:
|
|
- `POST /api/auth/login` / `logout` / `reset-password`
|
|
- `POST /api/register`
|
|
- `GET /api/me`
|
|
- `GET|POST /api/activity/{id}`
|
|
- `DELETE /api/activity/{id}`
|
|
- `POST /api/admin/users/{handle}/reset-password-code`
|
|
- `GET|POST /api/me/preferences` (once built)
|
|
|
|
**Layer 2 — human-readable (`docs/api.md`)**
|
|
|
|
A hand-written reference that groups endpoints by domain (auth, activities, admin,
|
|
sync), explains the overall auth model (cookie-based, httpOnly), rate limiting, and
|
|
covers things OpenAPI can't express well (SSE streams, error semantics, side effects
|
|
like rebuild triggers).
|
|
|
|
The OpenAPI spec and the hand-written doc are complementary, not duplicates:
|
|
OpenAPI is precise and machine-readable; `api.md` gives context and explains *why*.
|
|
|
|
---
|
|
|
|
## Tooling options
|
|
|
|
| Option | Pros | Cons |
|
|
|--------|------|------|
|
|
| Plain markdown in `docs/` | Zero tooling, lives in repo, renders on GitHub | No search, no versioning, no sidebar nav |
|
|
| MkDocs + Material theme | Beautiful, search, auto-nav from folder structure, can embed OpenAPI via plugins | Needs Python dep + build step; another thing to deploy |
|
|
| Docusaurus | Great for open-source projects, versioning, i18n | Node toolchain, heavier |
|
|
| VitePress | Fast, Vite-based (already in the stack), markdown + Vue | Still a separate site to host |
|
|
| Just the Swagger UI at `/api/docs` | Auto-generated, always up-to-date | Only covers the API, not user/admin/architecture |
|
|
|
|
**Recommendation:** Start with plain markdown in `docs/` — no build step, always
|
|
available, no new infrastructure. If the project goes public or the user base grows,
|
|
migrate to MkDocs Material (one `mkdocs.yml` + `pip install mkdocs-material`).
|
|
|
|
For the API specifically: enable the Swagger UI on the live server (currently it may
|
|
be disabled in production) so admins can explore it directly at `/api/docs`.
|
|
|
|
---
|
|
|
|
## Enabling Swagger UI in production
|
|
|
|
By default FastAPI serves `/docs` and `/redoc`. In `bincio serve`, the FastAPI app is
|
|
created with:
|
|
|
|
```python
|
|
app = FastAPI(docs_url=None, redoc_url=None) # check current value
|
|
```
|
|
|
|
For a private instance (auth-walled), it is safe to expose `/api/docs` — add a note
|
|
in `admin-guide.md` that it exists. Alternatively, serve it only when an env var is set.
|
|
|
|
---
|
|
|
|
## Suggested first milestone
|
|
|
|
1. Create `docs/` with `index.md`, `admin-guide.md`, `api.md`
|
|
2. `admin-guide.md`: deploy, init, invite, password reset, rebuild, reset data
|
|
3. `api.md`: auth endpoints + activity endpoints, hand-written
|
|
4. Enable Swagger UI on the server (or at least document that it exists at `/api/docs`)
|
|
5. Add Pydantic models to the 8 priority endpoints above
|
|
|
|
Everything else (user guide, architecture, developer guide, MkDocs) is second milestone.
|