docs

2026-02-21 17:53:29 +01:00 · 2026-02-21 17:53:29 +01:00 · ca565e2530
commit ca565e2530
parent c99af18ae4
26 changed files with 209 additions and 104 deletions
--- a/docs/developer/architecture.md
+++ b/docs/developer/architecture.md
@ -0,0 +1,25 @@
+# Domain Boundaries
+
+## Data Model Rules
+
+- Scholar tracking is user-scoped.
+- Publications are global/deduplicated records.
+- Read/favorite/visibility state stays on scholar-publication link rows.
+
+## Service Boundaries
+
+Canonical business logic belongs in `app/services/domains/*`.
+
+- `app/services/domains/ingestion/*`: run orchestration, continuation queue, scheduler, and scrape safety.
+- `app/services/domains/scholar/*`: fail-fast scholar parsing and source fetch adapters.
+- `app/services/domains/scholars/*`: scholar CRUD, profile image, and name-search controls.
+- `app/services/domains/publications/*`: listing/read-state, favorite toggles, enrichment scheduling, and retry paths.
+- `app/services/domains/crossref/*` + `app/services/domains/unpaywall/*`: DOI/OA enrichment with bounded pacing.
+- `app/services/domains/runs/*`: run history and continuation queue operations.
+- `app/services/domains/portability/*`: import/export workflows.
+
+## Frontend Behavior Notes
+
+- Mobile primary nav is in a left drawer and closes on route change or logout.
+- Long list views use internal scroll containers.
+- Name search remains intentionally constrained due upstream anti-bot behavior; production onboarding should prefer scholar ID/profile URL.
--- a/docs/developer/contributing.md
+++ b/docs/developer/contributing.md
@ -0,0 +1,24 @@
+# Contributing
+
+## Scope
+This project favors small, reviewable pull requests that keep runtime behavior clear and operationally safe.
+
+## Essential-File Policy
+Commit only source-of-truth files required to build, run, test, or document the app.
+
+Do not commit generated or local-only artifacts, including:
+- `__pycache__/`, `*.pyc`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`
+- frontend build/install outputs like `frontend/dist/`, `frontend/node_modules/`, `frontend/.vite/`
+- coverage outputs (`.coverage`, `htmlcov/`)
+- packaging/build leftovers (`*.egg-info/`, `build/`, `dist/`)
+- local probe/scratch material (`planning/`)
+
+CI enforces this with `scripts/check_no_generated_artifacts.sh`.
+
+## Merge Checklist
+- [ ] Changes are minimal, purposeful, and remove obsolete/dead code in touched areas.
+- [ ] Backend tests pass (`uv run pytest tests/unit` and integration scope as needed).
+- [ ] Frontend checks pass (`npm run typecheck`, `npm run test:run`, `npm run build`).
+- [ ] API/behavior docs are updated when env vars, endpoints, or payloads change.
+- [ ] `README.md`, `.env.example`, and deployment notes stay aligned.
+- [ ] `scripts/check_no_generated_artifacts.sh` passes locally.
--- a/docs/developer/documentation-standards.md
+++ b/docs/developer/documentation-standards.md
@ -0,0 +1,26 @@
+# Documentation Standards
+
+This project keeps docs organized by audience and document type.
+
+## Audience Split
+
+- `user/`: onboarding and usage tasks for self-hosted users.
+- `operations/`: runbooks and checklists for production operation.
+- `developer/`: architecture, contribution workflow, and implementation guides.
+- `reference/`: stable contracts (API, env variables, configuration behavior).
+
+## Document Quality Rules
+
+- One primary audience per page.
+- Task pages must include prerequisites, exact commands, and verification steps.
+- Reference pages should be contract-first and avoid procedural noise.
+- Runbooks should include recovery steps and rollback/safety notes.
+- Prefer concise pages with strong cross-links over long mixed-purpose pages.
+
+## Required Top-Level Entrypoints
+
+- `index.md`: user/developer/operator navigation hub.
+- `user/getting-started.md`: first-run path.
+- `developer/local-development.md`: contributor setup and validation path.
+- `operations/overview.md`: operational playbook index.
+- `reference/overview.md`: contract index.
--- a/docs/developer/frontend-theme-inventory.md
+++ b/docs/developer/frontend-theme-inventory.md
@ -0,0 +1,89 @@
+# Theme Inventory (Phase 0)
+
+This file captures the semantic color system baseline for the theme refactor.
+
+## Token Domains
+
+- `scale`:
+  - `brand` (`50..950`)
+  - `info` (`50..950`)
+  - `success` (`50..950`)
+  - `warning` (`50..950`)
+  - `danger` (`50..950`)
+- `surface`:
+  - `app`
+  - `nav`
+  - `nav_active`
+  - `card`
+  - `card_muted`
+  - `table`
+  - `table_header`
+  - `input`
+  - `overlay`
+- `text`:
+  - `primary`
+  - `secondary`
+  - `muted`
+  - `inverse`
+  - `link`
+- `border`:
+  - `default`
+  - `strong`
+  - `subtle`
+  - `interactive`
+- `focus`:
+  - `ring`
+  - `ring_offset`
+- `action` variants (`primary`, `secondary`, `ghost`, `danger`):
+  - `bg`
+  - `border`
+  - `text`
+  - `hover_bg`
+  - `hover_border`
+  - `hover_text`
+- `state` variants (`info`, `success`, `warning`, `danger`):
+  - `bg`
+  - `border`
+  - `text`
+
+## Theme Sources
+
+Theme presets are dynamically loaded from `frontend/src/theme/presets/*.{json,js}`.
+
+Current preset files:
+
+- `frontend/src/theme/presets/parchment.js`
+- `frontend/src/theme/presets/lilac.js`
+- `frontend/src/theme/presets/dune.js`
+- `frontend/src/theme/presets/oatmeal.js`
+- `frontend/src/theme/presets/scholarly.json`
+- `frontend/src/theme/presets/graphite.json`
+- `frontend/src/theme/presets/tide.json`
+
+Each preset contains both `light` and `dark` mode token definitions.
+
+## Adoption Status (Phase 0-3 complete baseline)
+
+Tokenized foundation components:
+
+- `AppButton`
+- `AppCard`
+- `AppCheckbox`
+- `AppEmptyState`
+- `AppHelpHint`
+- `AppInput`
+- `AppSelect`
+- `AppTable`
+- `AppModal`
+- `AppHeader`
+- `AppNav`
+- `AppAlert`
+- `AppBadge`
+- `RunStatusBadge`
+- `QueueHealthBadge`
+
+Hardening in place:
+
+- Frontend token policy check script: `frontend/scripts/check_theme_tokens.mjs`
+- CI enforcement step in `frontend-quality` workflow
+- Theme preset integrity tests in `frontend/src/theme/presets.test.ts`
--- a/docs/developer/local-development.md
+++ b/docs/developer/local-development.md
@ -0,0 +1,52 @@
+# Developer Local Development
+
+## Start the Dev Stack
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
+```
+
+Open:
+- API: `http://localhost:8000`
+- Frontend dev server: `http://localhost:5173`
+
+Stop:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml down
+```
+
+## Backend Validation
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app uv run pytest tests/unit
+docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app uv run pytest -m integration
+```
+
+## Frontend Validation
+
+```bash
+cd frontend
+npm install
+npm run typecheck
+npm run test:run
+npm run build
+```
+
+## Repository Gates
+
+```bash
+python3 scripts/check_frontend_api_contract.py
+python3 scripts/check_env_contract.py
+./scripts/check_no_generated_artifacts.sh
+```
+
+## Docs Site (Contributor Workflow)
+
+Docs tooling is colocated in `docs/website/`:
+
+```bash
+cd docs/website
+npm install
+npm run build
+```
--- a/docs/developer/overview.md
+++ b/docs/developer/overview.md
@ -0,0 +1,9 @@
+# Developer Documentation
+
+Use this section if you are contributing code or running full quality gates.
+
+- [Documentation Standards](./documentation-standards.md)
+- [Local Development](./local-development.md)
+- [Architecture Boundaries](./architecture.md)
+- [Contributing](./contributing.md)
+- [Frontend Theme Inventory](./frontend-theme-inventory.md)