bvandeusen
47e248d9ac
- README.md: reduced to overview + quick start + links to docs/ - docs/architecture.md: stack, design decisions, data models, key services - docs/configuration.md: all env vars, docker-compose setup, production + security - docs/development.md: dev workflow, CI/CD, migrations, release process - docs/features.md: detailed feature breakdown + keyboard shortcuts - docs/api-keys-and-mcp.md: API key management + Fable MCP install guide - docs/sso-oauth.md: OAuth/OIDC setup (replaces docs/oauth-setup.md) - docs/changelog.md: development history from summary.md - Remove summary.md (content distributed across docs/) - Remove docs/oauth-setup.md (superseded by docs/sso-oauth.md) - .gitignore: add .mcp.json Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
# Development
|
|
|
|
## Workflow
|
|
|
|
All development is Docker-based. Do not install Python or Node dependencies locally.
|
|
|
|
```bash
|
|
# Start the full stack (app + PostgreSQL + Ollama)
|
|
docker compose up --build
|
|
|
|
# Rebuild after backend changes (frontend changes require rebuild too)
|
|
docker compose up --build app
|
|
|
|
# Reset everything (wipes database)
|
|
docker compose down -v && docker compose up --build
|
|
|
|
# Run checks (lint, format, typecheck, tests)
|
|
make check
|
|
|
|
# Individual checks
|
|
make lint # ruff check src/
|
|
make fmt # ruff format src/
|
|
make typecheck # vue-tsc --noEmit
|
|
make test # pytest tests/
|
|
```
|
|
|
|
## Frontend Hot Reload
|
|
|
|
The Docker setup does not include Vite's hot-reload dev server. After frontend changes, rebuild the image. For faster iteration during active frontend work, you can run Vite locally:
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev # Vite dev server at http://localhost:5173
|
|
```
|
|
|
|
Point the Vite dev server at the backend by setting `VITE_API_BASE_URL=http://localhost:5000` (or configure `vite.config.ts` proxy).
|
|
|
|
## Database Migrations
|
|
|
|
Alembic migrations run automatically on container startup (`alembic upgrade head` in the `CMD`).
|
|
|
|
To create a new migration:
|
|
```bash
|
|
# Inside the running app container
|
|
docker compose exec app alembic revision -m "description_of_change"
|
|
# Edit the generated file in alembic/versions/
|
|
```
|
|
|
|
Migration conventions:
|
|
- Use raw SQL with `IF NOT EXISTS` guards for idempotency
|
|
- Use `DO $$ BEGIN CREATE TYPE … EXCEPTION WHEN duplicate_object THEN NULL; END $$` for enum types
|
|
- Number migrations sequentially (e.g. `0027_add_something.py`)
|
|
- Always provide both `upgrade()` and `downgrade()`
|
|
|
|
## CI/CD
|
|
|
|
### Pipeline
|
|
|
|
CI runs on Forgejo Actions with a custom runner base image (`py3.12-node22`):
|
|
|
|
| Trigger | Jobs | Docker tags pushed |
|
|
|---------|------|--------------------|
|
|
| Push to `dev` | typecheck + lint + test → build | `:dev`, `:<sha>` |
|
|
| Tag `v*` on `main` | typecheck + lint + test → build | `:latest`, `:<version>`, `:<sha>` |
|
|
| Push to `main` | typecheck + lint + test | (no build) |
|
|
|
|
### Release Process
|
|
|
|
1. Work on `dev` branch — CI validates on every push
|
|
2. When ready, open a PR from `dev` → `main` in Forgejo
|
|
3. Merge the PR
|
|
4. Create a release via the Forgejo UI on `main` with a `v*` tag (e.g. `v26.03.23.1` — CalVer: `YY.MM.DD.N`)
|
|
5. The tag push triggers CI → build job pushes `:latest` + `:<version>` Docker images
|
|
6. After merging to main, sync dev back:
|
|
```bash
|
|
git checkout dev && git merge main && git push origin dev
|
|
```
|
|
|
|
### Custom Runner
|
|
|
|
Runner base image: `infra/Dockerfile.runner-base` (Ubuntu 24.04 + Python 3.12 + Node 22 LTS).
|
|
Runner config: `infra/act-runner-config.yml` (label: `py3.12-node22`).
|
|
Runner compose: `infra/runner-compose.yml`.
|
|
|
|
To activate a new runner registration:
|
|
1. Copy `infra/act-runner-config.yml` → `/nfs/data/fabledsword/act_runner/config.yml`
|
|
2. Delete `/data/.runner` in the runner container
|
|
3. Restart the stack
|
|
|
|
### Docker Registry
|
|
|
|
Images pushed to: `git.fabledsword.com/bvandeusen/fabledassistant`
|
|
Cache tag: `:cache` (reduces build time ~80%)
|
|
|
|
Required secrets (repo → Settings → Secrets → Actions):
|
|
- `REGISTRY_USER` — Forgejo username
|
|
- `REGISTRY_TOKEN` — Forgejo PAT with `write:packages` scope
|
|
|
|
## Project Conventions
|
|
|
|
### Backend
|
|
|
|
- Services: `async with async_session() as session:` — import from `fabledassistant.models`
|
|
- No `fabledassistant.database` module
|
|
- Blueprint per resource: `routes/notes.py`, `routes/tasks.py`, etc.
|
|
- All business logic in `services/`; routes are thin wrappers
|
|
- Permission checks via `services/access.py` — never inline ownership checks in routes
|
|
|
|
### Frontend
|
|
|
|
- API calls via `frontend/src/api/client.ts` typed helpers (`apiGet`, `apiPost`, `apiPatch`, `apiDelete`)
|
|
- Pinia stores for shared state; local `ref()` for component-only state
|
|
- Composables in `composables/` for reusable behaviour (autosave, keyboard nav, tag suggestions, …)
|
|
- Views are page-level components in `views/`; reusable UI in `components/`
|
|
|
|
### Commit Style
|
|
|
|
```
|
|
type(scope): short description
|
|
|
|
Longer body if needed.
|
|
|
|
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
|
```
|
|
|
|
Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
|
|
Scopes: feature area (e.g. `chat`, `briefing`, `fable-mcp`, `notes`)
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
make test
|
|
|
|
# Run specific test file
|
|
docker compose exec app /opt/venv/bin/pytest tests/test_auth.py -v
|
|
```
|
|
|
|
Tests are in `tests/`. They run against a real PostgreSQL instance in CI (not mocked). Keep tests integration-style where possible — mock failures have historically masked real migration bugs.
|