Test Project Otto - Spec-Driven Web App

This folder contains a full spec-first blueprint for a nontrivial web application built fully in Brief.

Project Concept

Project name: SignalDesk

SignalDesk is an incident triage web app for small engineering teams. It tracks incidents, ownership, severity, SLA timers, status transitions, and audit history.

The app is intentionally chosen to exercise:

• Rich UI behavior (lists, filters, forms, timelines)
• Real backend business logic (state transitions and SLA computation)
• Durable storage and querying (Brief-native storage engine + indexed queries)

Artifacts

• spec/01-product-spec.md - Product scope, personas, and workflows
• spec/02-requirements.md - Functional and non-functional requirements
• spec/03-architecture.md - UI/backend/database architecture and runtime flow
• spec/04-delivery-plan.md - Milestones, tasks, and acceptance gates
• spec/05-brief-runtime-libraries.md - BriefNet/BriefJson/BriefStore design and acceptance tests
• contracts/openapi.yaml - Initial API contract
• db/schema.dbvs - Primary Data Brief schema for BriefStore
• db/schema.sql - SQL-compatible schema projection (compatibility/reference)

Build Direction (for next step)

Target implementation stack (proposed):

• UI: Rendered Brief (.rbv) + generated web output
• Backend API: Brief service (.bv) with custom HTTP/REST stack
• Database: BriefStore (Brief-native persistence and indexes)
• Platform libraries: custom BriefNet (HTTP/router), BriefJson (JSON), BriefStore (storage)
• Auth (phase 2): Session cookie + role checks in Brief service

How We Will Work

1. Lock requirements and API contracts first.
2. Build backend and database libraries in Brief to satisfy contracts.
3. Build UI against contract stubs/mocks.
4. Integrate and verify end-to-end behavior.
5. Add observability and hardening.

Milestone 1 Scaffold Status

Current milestone modules are implemented and compile on this branch:

• Service entrypoint: src/main.bv
• API orchestration: src/api/server.bv, src/api/router.bv, src/api/incidents.bv
• Domain rules: src/domain/incident_rules.bv
• Platform libraries: src/platform/briefnet/core.bv, src/platform/briefjson/core.bv, src/platform/briefstore/core.bv
• Contracts and models: src/contracts/models.bv, contracts/openapi.yaml, db/schema.dbvs
• Test scaffolds: tests/integration/incidents-lifecycle.md, tests/platform/brief-runtime-libraries.md

Implemented behavior includes:

• Incident creation validation (title, description, service, severity)
• Lifecycle transition enforcement with 409 conflict on invalid edges
• resolved transition requiring resolution_summary
• Version conflict checks on transition and note endpoints
• Status/severity filtering for incident list responses
• Deterministic timeline snapshots in incident responses

Compatibility note:

• This compiler build rejects String concatenation in Brief modules.
• Response assembly is therefore emitted through deterministic response literals rather than dynamic string building.

Run The Demo Now

Quick runnable experiment path:

bash test-project-otto/scripts/run_demo.sh

Full interactive UI demo:

bash test-project-otto/scripts/run_full_demo.sh

Then open http://localhost:4173 in your browser.

Notes:

• src/demo_quickstart.bv is the fastest executable harness for trying the flow.
• src/signalsdesk.rbv is the strict Brief-only rendered UI source.
• run_full_demo.sh is configured for no-mock operation and requires target/release/brief-compiler with rbv support.
• If the rbv compiler binary is unavailable, the script exits with an error and does not fall back to JS mocks.
• On some builds, Print# and println! output is not emitted at runtime even though the binary builds. The quickstart script falls back to inspecting embedded trace strings from the produced executable.

Import Resolver Note

Current Brief import resolution for modules under src/api/ requires API-local import paths.

For BriefJson this means:

• Canonical module: src/platform/briefjson/core.bv
• API mirror module: src/api/imports/platform/briefjson/core.bv

For domain rules this means:

• Canonical module: src/domain/incident_rules.bv
• API mirror module: src/api/imports/domain/incident_rules.bv

For local std helpers used by API imports:

• API std shim: src/api/imports/std/string.bv

Keep them synchronized with:

bash test-project-otto/scripts/sync_briefjson_adapter.sh
bash test-project-otto/scripts/sync_domain_rules_adapter.sh