bincio-activity/docs-proposal.md

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:

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.