FossilRepo

fossilrepo / CLAUDE.md

Source Rendered

Blame History Raw 54 lines

1	`# Claude -- fossilrepo`
2
3	Primary conventions doc: [`bootstrap.md`](bootstrap.md)
4
5	`Read it before writing any code.`
6
7	`## Project Overview`
8
9	`fossilrepo is an omnibus-style installer for a self-hosted Fossil forge. Django+HTMX management layer wrapping Fossil SCM server infrastructure with Caddy (SSL/routing), Litestream (S3 backups), and a sync bridge to GitHub/GitLab. Open source (MIT).`
10
11	`## Stack`
12
13	`- Backend: Django 5 (Python 3.12+)`
14	`- Frontend: HTMX 2.0 + Alpine.js 3 + Tailwind CSS (CDN)`
15	`- API: Django views returning HTML (full pages + HTMX partials)`
16	- ORM: Django ORM with `Tracking` and `BaseCoreModel` base classes
17	`- Auth: Session-based (Django native, httpOnly cookies)`
18	- Permissions: Group-based via `P` enum (`core/permissions.py`)
19	`- Jobs: Celery + Redis`
20	`- Database: PostgreSQL 16`
21	`- Linter: Ruff (check + format), max line length 140`
22	`- Fossil SCM: C binary, serves repos (each repo is a single .fossil SQLite file)`
23	`- Caddy: SSL termination + subdomain routing to Fossil instances`
24	`- Litestream: Continuous SQLite-to-S3 replication for backups`
25
26	`## Repository Structure`
27
28	```
29	`fossilrepo/`
30	`├── core/ # Base models, permissions, shared utilities`
31	`├── accounts/ # Authentication`
32	`├── organization/ # Org/team management`
33	`├── config/ # Django settings`
34	`├── templates/ # Django + HTMX templates`
35	`├── static/ # Static assets`
36	`├── docker/ # Caddy, Litestream container configs`
37	`├── fossil-platform/ # Old exploration (Flask + React), kept for reference`
38	`├── tests/ # pytest`
39	`├── docs/ # Architecture, guides`
40	`└── bootstrap.md # Project bootstrap doc -- read first`
41	```
42
43	`## Claude-specific notes`
44
45	- Prefer `Edit` over rewriting whole files.
46	- Run `ruff check .` and `ruff format --check .` before committing.
47	- Never expose integer PKs in URLs or templates -- use `slug` or `guid`.
48	- Auth check at the top of every view -- use `@login_required` + `P.PERMISSION.check(request.user)`.
49	- Soft-delete only: call `obj.soft_delete(user=request.user)`, never `.delete()`.
50	- HTMX partials: check `request.headers.get("HX-Request")` to return partial vs full page.
51	- CSRF: HTMX requests include CSRF token via `htmx:configRequest` event in `base.html`.
52	`- Tests: pytest + real Postgres, assert against DB state. Both allowed and denied permission cases.`
53	`- Fossil is the source of truth; Git remotes are downstream mirrors.`
54

FossilRepo

Keyboard Shortcuts