Project NEXUS Documentation¶
This directory contains the public, maintained documentation for Project NEXUS.
Historical prompts, one-off audits, dated handoff notes, generated reports, PDF exports, and stale planning documents were moved out of docs/ during the 2026-06-23 cleanup. They remain available locally under .local-docs-archive/2026-06-23-docs-cleanup/, which is intentionally ignored by git.
How the documentation is organised¶
This documentation follows the Diátaxis framework — four kinds of documentation, each with a different job:
| Kind | What it's for | Where it lives |
|---|---|---|
| Tutorial (learning) | A guided, hands-on first experience. | TUTORIAL.md |
| How-to guides (tasks) | Step-by-step recipes for a specific job. | Operations docs below; task sections inside each module guide. |
| Reference (information) | Precise, look-it-up facts. | The module guides, the API + openapi.json, and the architecture/platform docs. |
| Explanation (understanding) | The "why" behind the design. | ARCHITECTURE.md, I18N.md, DATABASE.md, CI.md, GOVERNANCE.md, DOCUMENTATION.md. |
New to the project? Start with the tutorial, then skim ARCHITECTURE.md, then dive into the module guide for whatever you're changing.
Getting Started¶
| Document | Purpose |
|---|---|
| TUTORIAL.md | Hands-on tutorial: clone, run, make a visible change, verify, and open a pull request. |
Architecture & Platform¶
| Document | Purpose |
|---|---|
| ARCHITECTURE.md | Maintained platform architecture map, runtime boundaries, and the tenant/feature model. |
| API.md | API getting-started + the openapi.json contract as source of truth. |
| api-reference.md | Interactive, browsable API reference (Redoc) — rendered on the documentation site. |
| I18N.md | Internationalisation: 11 languages, the recipient-locale rule, and the i18n quality gates. |
| DATABASE.md | Database, the two migration systems, the schema dump, and tenant scoping. |
| CI.md | The CI pipeline, which checks are blocking, PR gates, and how to run them locally. |
| TESTING.md | Test-layer meanings, E2E status, and generated-report policy. |
| CUSTOM-DOMAINS.md | Tenant custom-domain setup for the React and accessible frontends. |
| FEDERATION_API_MANUAL.md | Plain-English and technical federation API guide. |
| MODULES.md | The module map: every module → its code paths and guide. |
Module Guides¶
Curated, code-verified reference guides for every live module (docs/modules/):
| Guide | Module |
|---|---|
| admin | Admin permissions, tenant vs platform super-admin, audit surfaces. |
| ai-chat | AI assistant: provider abstraction, tools, privacy boundary with external providers. |
| blog-and-resources | Blog (posts, comments, RSS/SEO) and the resource library. |
| connections-and-reviews | Member connections, member reviews, and skill endorsements. |
| courses | Course catalogue, free + time-credit-paid enrolment, lessons, quizzes, certificates. |
| events | Events, RSVP/waitlists, recurring series, polls, organiser actions. |
| gamification | XP/levels, badges, leaderboards, challenges, NEXUS score, anti-abuse. |
| goals-and-impact | Goals, check-ins, milestones, community impact metrics, and SROI. |
| groups | Public/private groups, roles/permissions, discussions, files, moderation. |
| identity-verification | Document/selfie ID verification, the "ID Verified" badge, fee, and privacy. |
| ideation-challenges | Community challenges, idea submission, voting, and outcomes. |
| jobs | Vacancies, hiring pipeline, alerts, the bias/fairness audit, applicant GDPR. |
| listings | Timebanking offers/requests, lifecycle, categories, search indexing. |
| marketplace | Standalone marketplace with Stripe Connect payments, escrow, and click-and-collect. |
| members-and-gdpr | Member directory + GDPR (Article 17 deletion, DSAR export, consent, overdue alarm). |
| messaging | Conversations, attachments/voice, Pusher real-time, broker safeguarding, federation. |
| monetization | Premium subscriptions, merchant coupons, and local advertising. |
| notifications | In-app/email/push channels, the recipient-locale rule, dispatcher flow. |
| organisations | Organisation directory, registration/approval, opportunities, reviews, stats. |
| podcasts | Shows/episodes, audio hosting, RSS/iTunes feed, scheduled publishing. |
| search | Meilisearch architecture, indexes, tenant scoping, sync script, fallback. |
| social-feed | Activity stream, posts, polls (hidden-totals), stories, reactions, ranking. |
| volunteering | Hour logging, auto-mint approval, certificates, organisation roles, safeguarding. |
| wallet-exchanges | Time-credit ledger, transfers, the exchange lifecycle, and money invariants. |
Operations¶
| Document | Purpose |
|---|---|
| DEPLOYMENT.md | Production deployment workflow and blue/green commands. |
| RUNBOOK-INCIDENTS.md | First-response runbook for production incidents, with a post-mortem template. |
| MONITORING.md | External uptime checks, alert channels, and response notes. |
| SLO.md | Service-level objectives and wired alerting commands. |
| SENTRY.md | Backend and frontend Sentry configuration. |
| SECURITY-SCANNING.md | Public-safe scanner interpretation and suppression policy. |
Accessible Frontend¶
| Document | Purpose |
|---|---|
| govuk-alpha/RESEARCH.md | Accessible frontend architecture and GOV.UK Frontend constraints. |
| govuk-alpha/ATTRIBUTION.md | GOV.UK-related attribution notes. |
Governance¶
| Document | Purpose |
|---|---|
| DOCUMENTATION.md | Documentation architecture, standards, inventory classes, and maintenance workflow. |
| CONTRIBUTOR_TERMS_ENFORCEMENT.md | How PR gates enforce contributor terms and ownership acknowledgements. |
Project-level governance, release, and community-health documents live at the repository root: GOVERNANCE.md, RELEASES.md, CONTRIBUTING.md, SUPPORT.md, SECURITY.md, CODE_OF_CONDUCT.md.
Related Public Collateral¶
| Location | Purpose |
|---|---|
| ../docs-public/README.md | Public collateral and the prerender observability runbook. |
Publication Standards¶
Before adding a document here:
- keep it useful to a future maintainer, not just useful to one finished task;
- remove secrets, live credentials, private contact details, machine-local paths, and personal notes;
- avoid publishing raw prompts, handoffs, scratch plans, generated audit dumps, and exported PDFs;
- mark dated verification records clearly with the date and command used;
- prefer current code paths such as
app/,database/migrations/,routes/api.php, andreact-frontend/; - list every public document in this index;
- move local-only material to
.local-docs-archive/instead of committing it; - run
npm run check:docsbefore committing documentation changes. - run
npm run check:versionafter changing release/version labels or public collateral.
The docs hygiene check fails on task-output filenames, oversized docs, non-Markdown files, missing index links, broken local links, stale retired-doc references, old namespace/path references, stale platform-version phrases, generated artifacts in public doc paths, and obvious secret patterns.