Framework → category → control
217 controls across three frameworks, each with a status, an owner and its evidence. Readiness is implemented ÷ applicable.
Documentation
How it is organised,
and how to use it.
The orientation. The authoritative documents ship in the repository, versioned with the code.
Concepts
Eight ideas, and you have the model.
Folders and documents
A tree built from the libraries. Access is view, edit or manage per folder, inherited downward. Documents carry a review cadence.
Evidence links
Many-to-many between controls and documents, so one policy can answer CC6.1, A.5.15 and 7.1.
Risks
A 5×5 likelihood × impact register with treatment, owner, due date and notes. CSV and XLSX in, CSV out.
Access reviews
A snapshot of every account, marked keep, modify or revoke. Read-only once complete.
Audit trail
Every write, sign-in and sign-out, with actor, record, field names (never values) and IP. The API cannot edit it; the Django admin can, so keep /admin/ off the network.
Readiness history
A daily snapshot. Trends come from history, not from a figure recomputed on each view.
Workspaces
The tenant. Every organisation-owned row belongs to one. A single-organisation install has one, called Default.
Roles
Who can do what.
The API enforces every capability. The interface only offers what the API would accept.
| Role | Can |
|---|---|
| Administrator | Everything. Cannot lock themselves out or leave a workspace without an active administrator. |
| Compliance Manager | Controls, all folders and documents, risks, meetings, vendors and packages. |
| Control Owner | Documents in granted folders, their own risks, meeting minutes, and PBC lines assigned to them. |
| Auditor | Read-only, capped at view. Reads the registers any account can, and folders granted to them. An external auditor reaches package evidence only through a package grant. |
| Viewer | Granted folders and the shared registers. No writes. |
| Custom roles | Built from the same six capability flags. |
How effective folder access is resolved
Folder.effective_access(user) returns the highest of: 1. manage if superuser, or role.can_manage_folders 2. view if role.can_view_all 3. manage if the user owns the folder 4. the strongest FolderPermission for the user or their role on this folder or any ancestor (inheritance) then: an Auditor role is capped at view. Documents inherit their folder's access. A document owner may always edit their own document; deleting it requires manage on the folder. Re-parenting requires manage on the folder and edit on the destination. Generated framework folders are immutable through the API.
Screen by screen
The day-to-day reference.
| Screen | What you do there | Who |
|---|---|---|
| The top bar | Four tabs, the Governance menu, Ctrl K search, appearance, notifications and your account. | Everyone |
| Dashboard | Readiness, the lead schedule, the coverage atlas, what needs attention and the calendar. | Everyone |
| Analytics | Readiness per framework, status mix, review load and ownership coverage. | Everyone |
| Controls | Filter, set status and owner, attach or unlink evidence, export CSV. | Read: everyone Write: managers |
| Documents | Upload, version, review, map controls and manage folder access. | By folder grant |
| Risks | Create, import, edit, note and export. | Write: managers or the risk's owner |
| Vendors | Assurance and expiry, the responsibility matrix, and questionnaires sent to the vendor. | Read: everyone Write: managers |
| Responsibility | RACI per control across people and vendors, gaps counted. | Read: everyone Write: managers |
| Audit packages | Assemble, seal, issue and withdraw. Samples and the PBC request list. | Assemble: managers Conclude: the issued auditors |
| Users | Accounts, roles, deactivation and second-factor resets. | Administrators |
| User audit | Snapshot every account, decide per row, then complete. | Administrators Auditors: read-only |
| Audit log | Filter by action, record, user and time; search by IP. | Administrators, auditors, view-all managers |
| Meetings | Series with a yearly cadence, and their minutes. | Add series: managers Minutes: owners |
| Groups | Champion groups by department, with an accountable owner. | Administrators |
| Jira | One Atlassian site per workspace, boards tracked read-only. The token stays on the server. | Connect: administrators Read: everyone |
| Settings | Profile, appearance, security, notifications, role and access, about. | Everyone, for themselves |
The narrative version: USER_GUIDE.md.
API
The interface is a client of it.
Anything the interface can do, a script can do, under the same permissions and the same audit trail.
Authentication
POST /api/auth/token/→ access (60 min) + refresh (7 days)- With a second factor:
{ mfa_required, factors }until anotporpasskeyis supplied POST /api/auth/token/refresh/rotates and blacklists the old tokenPOST /api/auth/logout/blacklists the current one- HttpOnly cookies by default, with
__Host-prefixes
Conventions
- Every query is scoped to the caller's workspace. A superuser may pass
X-Workspace: <slug> - Login and refresh are throttled per client, shared across workers in Docker. There is no account lockout
- Writes log the field names touched, never secrets
GET /api/health/is open on purpose: status, version, database, demo accounts, scanner and signing
| Endpoint | Purpose |
|---|---|
/api/frameworks/ · /api/controls/ | Libraries, statuses, owners, the crosswalk and CSV export. |
/api/folders/ · /api/documents/ | The tree, uploads, versions, reviews and folder grants. |
/api/documents/{id}/preview/ | The viewer's render: grant-gated, audited, byte-checked. |
/api/risks/ · /api/risk-notes/ | The register, notes and the importer. |
/api/access-reviews/ | Snapshots, decisions, export and completion. |
/api/vendors/ | Register, assurance and the matrix: get, put, parse and export. |
/api/questionnaire/<token>/ | What a vendor answers, with no account. Token-scoped and throttled. |
/api/evidence-packages/ · /api/package-samples/ | Assemble, seal, issue, withdraw, the bundle and sample verdicts. |
/api/pbc-requests/ · /api/pbc-items/ | The auditor's request list. |
/api/signing-keys/ | Public keys and fingerprints, open so an auditor can check a bundle. One key per installation. |
/api/workspaces/ | Superusers create and archive. Nothing is ever deleted. |
/api/audit-log/ · /api/notifications/ · /api/analytics/summary/ | The trail, the personal feed and the dashboard summary. |
The Django admin at /admin/ sits outside the role model: no second factor, no throttle, and its session reaches all of /api/. Put it behind a VPN or an allow-list.
Data model
The essentials, in one block.
Eleven Django apps. Every organisation-owned model carries a workspace key, and its manager applies the filter on every query.
Not tenant-scoped, on purpose: the workspace list, per-person sign-in state, the signing keys and delivery receipts.
Full architecture notesessentials
Framework 1─* ControlCategory 1─* Control *─* ControlMapping │ 1─* ControlEvidence *─1 Document User(Role) ─owns→ Control / Folder / Document / Risk Folder (self-parent tree, cycle-guarded) │ 1─* Document 1─* DocumentVersion │ └─ owner, review_cadence, next_review_date, │ reminders_sent, scan verdict / quarantine └─ FolderPermission (role|user → view/edit/manage, inherited) Risk 1─* RiskNote AccessReview 1─* AccessReviewItem MeetingSeries 1─* MeetingMinute ChampionGroup 1─* GroupMember Vendor 1─* VendorAssessment ├─ 1─* SharedResponsibility (the matrix) ├─ 1─* Responsibility (RACI rows, keyed on Control) └─ 1─* QuestionnaireInvite (token hash only) EvidencePackage 1─* PackageControl 1─┬─* PackageEvidence └─* PackageSample ├─ 1─* PackageGrant (the audited folder-permission bypass) ├─ 1─* PbcRequest 1─* PbcItem └─ prior_package → roll-forward chain AuditLog · ReadinessSnapshot · CalendarEvent · NotificationReceipt MfaDevice · WebAuthnCredential · SigningKey User 1─* MfaBackupCode every organisation-owned row above → workspace_id
Operations
The command
reference.
On Docker, prefix with docker compose exec backend python.
Scheduled: one run covers every workspace
manage.py send_review_reminders [--dry-run] manage.py record_readiness manage.py scan_evidence manage.py send_digests manage.py flushexpiredtokens
Administration
manage.py createsuperuser
manage.py seed_frameworks --with-folders
manage.py seed_frameworks --roles-only
manage.py remove_demo_data [--delete]
[--workspace slug]
manage.py rotate_signing_key
manage.py link_oidc_identity
manage.py test_mailbox --to you@example.comIn the repository
Versioned with the code.
If this site and the repository disagree, the repository wins.
README.md
The whole product in one document.
INSTALL.md
Every install path, and how each one fails.
PREREQUISITES.md
What to have ready, per platform.
GETTING_STARTED.md
A guided first hour.
USER_GUIDE.md
Concepts, roles and every screen.
docs/ARCHITECTURE.md
Apps, tenancy, RBAC, auth and topology.
SECURITY.md
The threat model, residual risks and every review on record.
REVIEWS.md
Seven detailed review records, every finding and where it stands. SECURITY.md lists all thirteen reviews.
TESTING.md · VALIDATION.md
How the gates run and what each proves.
CHANGELOG.md
Every release, with upgrade notes.
ROADMAP.md
What shipped, what is next, what is parked and why.
.env.example
Every environment variable, with its default.