BrainDump — Development Report

Project: BrainDump v1.0.0 Type: Web Application (Node.js + React) Profile: Commercial Source: github.com/loskylp/BrainDump Production: braindump.nxlabs.cc Session transcript: BrainDump-TRANSCRIPT.md Retrospective: BrainDump-RETROSPECTIVE.md Dates: 2026-03-17 to 2026-03-22

---

Overview

BrainDump is a public, multi-user web application for technical documentation management. It provides a split-pane editing experience — Markdown source with syntax highlighting on the left, real-time CommonMark-rendered preview on the right — with a persistent note catalog, full-text search, folder organisation, version history, auto-save, and a global tagging system. The service runs on shared infrastructure at nxlabs.cc with CI/CD managed by GitHub Actions, Watchtower, Traefik, and Uptime Kuma.

The project was developed as the second production test of the Nexus SDLC framework — the first to exercise all major agents (Methodologist, Orchestrator, Analyst, Auditor, Architect, Scaffolder, Planner, Builder, Verifier, Sentinel, DevOps) at Commercial profile, across three full delivery cycles, culminating in a live Go-Live against production infrastructure.

---

Initial Prompt

“@nexus-methodologist I want to build BrainDump (a knowledge base): a web system for saving notes with Markdown support”

---

Lifecycle Summary

The development ran through three full delivery cycles and all Nexus SDLC gates. Every gate required explicit human (Nexus) approval before the swarm could proceed.

Gate	Date	Status	Notes
Requirements Gate	2026-03-19	Approved	17 requirements (4 iterations to incorporate expanded brief, persona, and Auditor fixes)
Architecture Gate	2026-03-19	Approved	9 ADRs, 56 fitness functions, all 17 requirements covered
Plan Gate — Cycle 1	2026-03-19	Approved	14 tasks; walking skeleton (TASK-016) as first deliverable; TASK-019 cut below line
Cycle 1 Execution	2026-03-21	Complete	14/14 tasks PASS; 1 context-limit interruption recovered cleanly
Demo Sign-off — Cycle 1	2026-03-21	Accepted	ESC-002 CI incident resolved; Playwright validation; 12 screenshots committed
Plan Gate — Cycle 2	2026-03-21	Approved	10 tasks; 2 untraced features flagged and formalised before Builder
Requirements Gate — v3	2026-03-21	Approved	REQ-018 and REQ-019 added at Plan Gate; mini Requirements Gate run first
Cycle 2 Execution	2026-03-21	Complete	10/10 tasks PASS; staging live at braindump.staging.nxlabs.cc
Demo Sign-off — Cycle 2	2026-03-21	Approved	Playwright validation; 2 inline bug fixes; screenshots committed
Requirements Gate — v4	2026-03-21	Approved	REQ-020 ZIP export, REQ-021 tagging, REQ-022 reading mode
Plan Gate — Cycle 3	2026-03-22	Approved	7 tasks including production deploy and monitoring
Cycle 3 Execution	2026-03-22	Complete	7/7 tasks PASS; many tasks dispatched in parallel
Demo Sign-off — Cycle 3	2026-03-22	Approved	12/12 Playwright scenarios PASS; 0 unresolved Sentinel findings
Go-Live — v1.0.0	2026-03-22	Approved	Production live at braindump.nxlabs.cc

---

Requirements

The requirements set evolved across four versions through two formal Requirements Gates and one mid-cycle mini-gate. The initial prompt produced 14 requirements; three rounds of refinement added the split-pane editor specification, note catalog, full-text search, auto-save, version history, landing page, keyboard shortcuts, export, and three Cycle 3 features requested at demo.

ID	Requirement	Priority	Origin
REQ-001	User registration (username, email, password; duplicate email rejected)	Must Have	Initial
REQ-002	User login and logout (session-based; protected routes)	Must Have	Initial
REQ-003	Password reset via email (expiring link; no user enumeration)	Must Have	Expanded brief
REQ-004	Create a note (title required; opens split-pane editor immediately)	Must Have	Initial
REQ-005	Edit a note (title and body; persisted via auto-save)	Must Have	Initial
REQ-006	Delete a note (with confirmation; cascades to all versions)	Must Have	Initial
REQ-007	Split-pane Markdown editor with live CommonMark preview (syntax highlighting; real-time render; no manual render action)	Must Have	Expanded brief
REQ-008	Note catalog sidebar (persistent; chronological; always visible; primary navigation)	Must Have	Expanded brief
REQ-009	Organize notes in folders (single-level in v1; folder delete moves notes to root)	Must Have	Brief v1
REQ-010	Full-text search using PostgreSQL FTS (title + body; weighted; ranked results)	Must Have	Expanded brief
REQ-011	Per-user data isolation (application-level + PostgreSQL Row-Level Security)	Must Have	Architecture Gate
REQ-012	Timestamps on all notes (created date, last modified date)	Must Have	Initial
REQ-013	Responsive web design (three-panel at ≥1024px; progressive collapse below)	Must Have	Brief v1
REQ-014	Account deletion (cascades all notes, versions, folders; permanent)	Must Have	Brief v1
REQ-015	Auto-save with debounce (2-second debounce; separate from version creation)	Must Have	Expanded brief
REQ-016	Note version history (30-second idle + any change = new version; all versions retained indefinitely; restore from history)	Must Have	Expanded brief
REQ-017	Public landing page (app description, feature highlights, registration CTA)	Must Have	Audit finding AUDIT-001
REQ-018	Keyboard shortcuts (Cmd/Ctrl+B bold, Cmd/Ctrl+I italic; others per plan)	Should Have	Plan Gate request
REQ-019	Export note as Markdown (single-note download)	Should Have	Plan Gate request
REQ-020	Full export to ZIP (complete collection; current content only; folder structure preserved)	Should Have	Cycle 2 demo request
REQ-021	Global tagging system (Unicode letters/digits/hyphens; case-insensitive dedup; OR filter; search integration)	Should Have	Cycle 2 demo request
REQ-022	Reading mode (distraction-free rendered view; keyboard toggle)	Should Have	Cycle 2 demo request

Non-functional requirements:

• PostgreSQL as the database engine (Nexus-decided)
• Monolithic server architecture (Nexus-decided)
• Professional/technical design aesthetic throughout (ADR-008)
• Rate limiting on authentication endpoints (security; SEC-001 → TASK-024)
• CI pipeline passing before Builder tasks begin (DevOps exit criterion)

---

Architecture

System metaphor: A personal library with a card catalog — each user has their own locked room containing their notes, organized in labeled drawers (folders), with a librarian’s index card system (full-text search) for fast retrieval. The librarian automatically stamps each card’s revision history as the writer pauses between sessions.

The system is a monolithic server-rendered web application backed by PostgreSQL. The frontend is a single-page React application shell served by the backend, providing a three-panel workspace: catalog sidebar, Markdown source editor, and live CommonMark preview.

Browser (React SPA)
  ├── Catalog sidebar       ← note list, folder tree, tag filter, search
  ├── Editor panel          ← CodeMirror 6 (syntax highlighting, shortcuts)
  └── Preview panel         ← markdown-it (live CommonMark rendering)
        ↕ REST API
Node.js + Express (monolith)
  ├── Auth routes           ← session-based, express-session, bcrypt
  ├── Note / Folder / Tag routes  ← ownership guard middleware
  ├── Version creation      ← 30-second idle timer + diff check
  └── FTS routes            ← PostgreSQL tsvector + GIN index
        ↕ Sequelize ORM
PostgreSQL 16
  ├── users, notes, note_versions, folders, sessions
  ├── tags, note_tags
  ├── GIN tsvector index on notes
  └── Row-Level Security policies (defense-in-depth)

Key decisions (ADRs):

ADR	Decision	Reason
ADR-001	Node.js + Express, React, CodeMirror 6, markdown-it, Sequelize	Unified JS stack; CodeMirror for production-grade editing; markdown-it is CommonMark-compliant
ADR-002	Server-side sessions (express-session + connect-pg-simple), bcrypt	Session-based auth suits monolith; PostgreSQL-backed sessions survive restarts
ADR-003	Five-table relational schema + WAL-mode PostgreSQL	Referential integrity, CASCADE deletes, data durability
ADR-004	Client-side 2s debounce for auto-save + 30s idle for versioning	Two distinct timers map directly to REQ-015/REQ-016; server-side diff authoritative
ADR-005	PostgreSQL FTS: maintained tsvector + GIN index, weighted by title/body	Weighted vectors match Carla’s search-by-keyword workflow; sub-linear at scale
ADR-006	Application-level ownership guard + PostgreSQL RLS	Belt and suspenders for per-user isolation
ADR-007	Two Docker containers on nxlabs.cc (staging + production), shared Traefik + Watchtower + Uptime Kuma	Integrates with existing shared infrastructure; Watchtower handles auto-deploy
ADR-008	Tailwind CSS with constrained design token system	Locked config enforces professional/technical aesthetic without a Designer agent
ADR-009	Progressive collapse responsive layout (CSS Grid, three breakpoints)	Preserves information hierarchy at all viewport widths

Cycle 3 added two further ADRs: ADR-010 (tagging schema — UUID tags table, note_tags junction, tsvector trigger update) and ADR-011 (ZIP export via streaming archiver package).

---

Execution Plan

The planner produced three task plans across the lifecycle. TASK-016 (workspace shell) was designated the first meaningful deliverable — all other UI and API tasks depend on it.

Cycle 1 — Walking Skeleton and Core (14 tasks)

Task	Description	Covers	Iterations
TASK-001	DevOps Phase 1 — CI pipeline, dev environment, Docker	Infrastructure	— (DevOps)
TASK-016	Workspace layout shell and routing	Foundation	2
TASK-002	Database schema, migrations, RLS role separation	REQ-011, REQ-012	1
TASK-003	User registration	REQ-001	2
TASK-004	User login and logout	REQ-002	2
TASK-005	Ownership guard middleware and data isolation	REQ-011	2
TASK-006	Create a note with persistence	REQ-004	1
TASK-008	Note catalog sidebar	REQ-008	2
TASK-011	Public landing page	REQ-017	1
TASK-007	Split-pane Markdown editor with live preview	REQ-007	1
TASK-009	Edit a note (API and editor integration)	REQ-005	1
TASK-010	Delete a note	REQ-006	1
TASK-012	Auto-save with debounce	REQ-015	1
TASK-013	Note version history	REQ-016	1

Cycle 2 — Full Feature Set (10 tasks)

Task	Description	Covers	Iterations
TASK-024	Rate limiting on auth endpoints	SEC-001 (deferred from Cycle 1)	1
TASK-014	Full-text search	REQ-010	1
TASK-015	Password reset flow	REQ-003	1
TASK-017	Folder organisation	REQ-009	2
TASK-021	DevOps Phase 2 — staging deploy, CI completion	Infrastructure	— (DevOps)
TASK-018	Responsive design	REQ-013	1
TASK-025	Keyboard shortcuts	REQ-018	2
TASK-026	Export notes as Markdown	REQ-019	1
TASK-019	Account deletion	REQ-014	1
TASK-020	Fitness function instrumentation	NFR verification	1

Cycle 3 — Stakeholder Features and Production (7 tasks)

Task	Description	Covers	Notes
TASK-027	Tagging backend — schema, model, API, search integration	REQ-021	ADR-010
TASK-028	Tagging frontend — UI integration	REQ-021	Depends on TASK-027
TASK-029	Bulk export to ZIP	REQ-020	ADR-011
TASK-030	Reading mode	REQ-022
TASK-031	DevOps Phase 3 — production environment	Infrastructure	— (DevOps)
TASK-032	Production monitoring — Uptime Kuma + AutoKuma	Infrastructure	— (DevOps)
TASK-033	Sentinel security review — Cycle 3	Security	2 Medium findings fixed inline

---

Implementation

Repository: github.com/loskylp/BrainDump Language: JavaScript (Node.js 20 backend, React 18 frontend) Backend dependencies: Express, Sequelize, express-session, connect-pg-simple, bcrypt, nodemailer, archiver, express-rate-limit Frontend dependencies: React, CodeMirror 6, markdown-it, Vite

Key backend modules

backend/src/middleware/ownership.js Injects req.user.id into every authenticated request and enforces ownership on all note, folder, tag, and version operations. Combined with PostgreSQL RLS policies as a second enforcement layer (ADR-006).

backend/src/routes/notes.js Full CRUD for notes including auto-save endpoint (PUT /api/notes/:id), version creation trigger (POST /api/notes/:id/versions), and full-text search (GET /api/notes?q=). Ownership guard applied on every route.

backend/src/routes/auth.js Registration, login, logout, and password reset. Rate-limited at 10 requests per 15-minute window. Password reset tokens expire after 1 hour; response is identical for registered and unregistered emails (prevents user enumeration, REQ-003).

backend/src/routes/tags.js Tag CRUD, note-tag associations, and tag-filtered note listing. Tag names are normalized to lowercase; creates if not exists on inline creation. OR logic for multi-tag filter.

backend/migrations/ Seven migration files covering the full schema lifecycle: users → sessions → notes → note_versions → folders → tags + note_tags + tsvector trigger update. Each migration includes a down method.

Key frontend modules

frontend/src/components/Editor.jsx CodeMirror 6 integration with Markdown language support, key binding map (Cmd/Ctrl+B, Cmd/Ctrl+I), and 2-second debounce wired to the auto-save API. Reading mode toggle collapses the editor panel and expands the preview to full width.

frontend/src/components/Sidebar.jsx Note catalog with tag filter badges above the list, folder tree navigation, “New Note” button, and “Export All” button. Handles empty state, loading, and error states.

frontend/src/hooks/useVersionHistory.js Manages the 30-second client-side idle timer. On expiry, calls the version-check API endpoint; the server creates a version only if the content has changed since the last version. Timer resets on any keypress.

CI/CD pipeline (GitHub Actions)

Five jobs run on every push to main and on every release tag (v*):

Job	What it does
backend-lint	ESLint on backend source
backend-unit	Jest unit tests for all backend routes and models
backend-integration	Acceptance tests against a real PostgreSQL service container
frontend-lint	ESLint on frontend source
frontend-test	Vitest unit tests for React components and hooks

On v* tags, an additional job builds and pushes the Docker image to ghcr.io/loskylp/braindump:latest. Watchtower on nxlabs.cc polls the registry and performs a zero-downtime restart when a new digest lands.

---

Verification

Each task was verified by the Verifier agent running unit tests, acceptance tests, and (from Cycle 2 onward) CI regression confirmation against the live staging environment.

Cycle 1 — 448 tests at Demo Sign-off

Task	AC	Tests	CI
TASK-016 Workspace shell	6/6	43	—
TASK-002 Schema + RLS	10/10	140	—
TASK-003 Registration	6/6	295	—
TASK-004 Login/logout	6/6	268	—
TASK-005 Ownership guard	7/7	335	—
TASK-006 Create note	6/6	419	—
TASK-008 Catalog sidebar	5/5	246	—
TASK-011 Landing page	6/6	549	—
TASK-007 Markdown editor	8/8	626	—
TASK-009 Edit note	5/5	480	—
TASK-010 Delete note	6/6	397	—
TASK-012 Auto-save	7/7	407	—
TASK-013 Version history	10/10	448	—

Sentinel — Cycle 1: SEC-001 (High: missing rate limiting on auth endpoints) deferred to Cycle 2 as TASK-024. SEC-003 (High: missing security headers) resolved inline by Sentinel before Demo Sign-off.

Demo Sign-off — Cycle 1: 12 Playwright scenarios validated against staging. Screenshots committed to tests/demo/. Two blocking issues required resolution before sign-off (see CI incident ESC-002 below).

Cycle 2 — CI green on all 5 jobs; staging confirmed per task

Task	AC	Result	CI Run
TASK-024 Rate limiting	6/6	PASS	23376742012
TASK-014 Full-text search	10/10	PASS	23383138143
TASK-015 Password reset	8/8	PASS	23383805381
TASK-017 Folder organisation	9/9	PASS	23385024748
TASK-021 DevOps Phase 2	8/8	PASS	23385582169
TASK-018 Responsive design	6/6	PASS	23386191945
TASK-025 Keyboard shortcuts	8/8	PASS	23388053947
TASK-026 Export as Markdown	7/7	PASS	—
TASK-019 Account deletion	5/5	PASS	23386531154
TASK-020 Fitness instrumentation	FF-D24/D04/D12/D16	PASS	23387142494

Demo Sign-off — Cycle 2: Playwright demo validation complete. Two inline bug fixes applied: TASK-025 keyboard shortcut styling, TASK-018 mobile sidebar. Screenshots committed.

Cycle 3 — All tasks verified PASS

Task	AC	Result
TASK-027 Tagging backend	12/12	PASS
TASK-028 Tagging frontend	AC set	PASS
TASK-029 Bulk ZIP export	10/10	PASS
TASK-030 Reading mode	AC set	PASS
TASK-031 DevOps Phase 3	7/10 PASS, 3 DEFERRED (operator actions)	PASS
TASK-032 Production monitoring	AutoKuma confirmed	PASS
TASK-033 Sentinel security review	0 Critical, 0 High unresolved	PASS

Demo Sign-off — Cycle 3: 12/12 Playwright scenarios PASS. Sentinel Medium findings resolved inline with Verifier confirmation. Screenshots committed.

Go-Live: v3.0.0 tag pushed, CI ran all 5 jobs green, Watchtower pulled :latest and started production container. First health check returned db: disconnected (transient warmup state); confirmed healthy within 60 seconds. Nexus confirmed: “Go live was a success.”

---

ESC-002 — CI Incident (2026-03-21)

Between Cycle 1 completion and Demo Sign-off, the CI pipeline and staging environment were both unreachable. Four root causes were identified and fixed:

1. No test:unit script in backend/package.json — CI job failed silently
2. Missing ESLint config in backend/ — lint job failed on push
3. Missing migration step before integration tests — tests ran against empty schema
4. Frontend served only in NODE_ENV=production — staging used NODE_ENV=staging, so static files were never served

All four were fixed by the DevOps agent. Staging became reachable after an additional fix: Express session secure: true was set unconditionally, but nxlabs.cc terminates TLS at Traefik, so req.secure === false inside the container. Fix: trust proxy 1 added to Express config, enabling req.secure via the X-Forwarded-Proto header.

---

Agents Active

The Methodologist configured a full Commercial-profile swarm. Designer and Scribe were skipped; Builder handled UI directly from requirements, reviewed at Demo Sign-off.

Agent	Role	Contributed
Methodologist	Set profile, configured active agents, managed retrospectives and manifest updates	Methodology Manifest (3 versions)
Orchestrator	Routing, state management, gate transitions, escalation log	project-state.md, escalation-log.md, routing slips (20+)
Analyst	Requirements discovery, brief writing, domain model, requirement iterations	brief-v2.md, requirements-v4.md (4 versions)
Auditor	Requirements consistency and testability review, architecture audit	Audit reports for Requirements Gate and Architecture Gate
Architect	System design, ADR production, fitness functions	architecture-overview-v1.md, 11 ADRs, 56 fitness functions
Scaffolder	Per-cycle code structure scaffolding (3 cycles)	Signatures, contracts, TODO-marked stubs for each cycle
Planner	Task decomposition (3 cycles, three-pass analysis)	task-plan-v3.md (3 versions), dependency graphs
Builder	Implementation of all 31 tasks	Source code, unit tests, migrations, CI configuration
Verifier	Acceptance testing, CI monitoring, staging confirmation, commit protocol	Verification reports, acceptance test files, demo scripts
Sentinel	Security review (3 cycles)	SEC-001 through SEC-003 findings; Cycle 3 Medium findings resolved
DevOps	CI/CD pipeline, Docker setup, staging and production environments	docker-compose files, GitHub Actions workflows, deploy runbook

---

Framework Observations

This run exposed 22 distinct framework improvement opportunities, documented in detail in BrainDump-RETROSPECTIVE.md. Summary of the most impactful:

Orchestrator role discipline:

• The Orchestrator collapsed into a general-purpose agent in three patterns: direct task execution instead of dispatch (Pattern A), CI emergency self-service (Pattern B), and post-context-resume dispatch failures (Pattern C). Manifest v2 codified Rules 1 and 2 after Cycle 1; compliance improved significantly in Cycle 2.
• Gate approval must authorise the full phase sequence — not just the first step. The Orchestrator asked for permission to call the Scaffolder after the Plan Gate was already approved.

DevOps and CI discipline:

• TASK-001 was marked COMPLETE after file inspection — without a real push and green CI run. Four silent CI failures only surfaced during Cycle 1 execution. Rule added: DevOps Phase 1 is only COMPLETE after a push and a green CI run for all jobs.
• The Verifier commit/push/CI protocol was not defined. Task is now only COMPLETE when the Verifier commits, pushes, and CI regression passes. Builder must not push.

Process artefact hygiene:

• No commits were made for process/ artefacts during Cycle 1. If a context limit had hit before the final session commit, the routing slips, requirements, and architecture documents would have been unrecoverable from git history. Rule added: commit process artefacts after each agent produces output.

Demo validation:

• Demo scripts were written as markdown documents with curl instructions — not executed. Cycle 3’s tagging feature had no demo script; TASK-029’s demo covered only the backend API. Rule added: demo scripts must be executed via Playwright with committed screenshots as evidence.

Framework infrastructure established:

• The skills/ collection was created as a direct outcome of this project — starting with bash-execution.md, commit-discipline.md, demo-script-execution.md, and traceability-links.md.
• The cd <dir> && <command> pattern triggered repeated permission prompts throughout. Rule added: all commands run from the working directory; no cd compound forms.

---

Usage

# Development
cd frontend && npm install && npm run dev   # Vite dev server
cd backend && npm install && npm start       # Express API

# Run full test suite
cd backend && npm test                       # Jest unit + acceptance
cd frontend && npm test                      # Vitest

# Docker (staging)
docker compose -f docker-compose.dev.yml up -d

# Acceptance tests only
cd backend && npx jest tests/acceptance/

# Demo scripts (Playwright)
cd tests/demo && npx playwright test

---

Outcome

BrainDump v1.0.0 shipped with all 22 requirements satisfied across 31 tasks and 3 delivery cycles. The project ran from first prompt to production Go-Live in six days (2026-03-17 to 2026-03-22). The production service is live at braindump.nxlabs.cc.

As a framework validation, this run confirmed that the Commercial profile handles a real-world multi-cycle web project — managing scope growth, mid-cycle feature requests, a CI incident, security findings, and production deployment — while maintaining gate discipline and audit traceability. It also exposed 22 concrete framework improvement opportunities that were addressed before the next project begins, producing the skills/ collection and four new Manifest rules that address the most impactful failure modes observed.