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