add architecture graph generator and docs
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).
This commit is contained in:
Davide Scaini
@@ -0,0 +1,113 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user