Skip to content

release-build-notes.md

Latest commit

 

History

History
255 lines (190 loc) · 11.2 KB

release-build-notes.md

File metadata and controls

255 lines (190 loc) · 11.2 KB
Raw

Release Build Notes

1. Release Version and Changelog

Version: 1.0.0 Release Date: 2026-05-12 Project: Project.superMindmap Platform: Terra V0.5.0

Changelog

New Features

  • Multi-Agent Pipeline Orchestration: Sequential pipeline execution across four agent roles (Product Manager → Designer → Developer → QA Engineer) with state-machine-driven stage transitions.
  • State Machine Engine: Nine-stage pipeline state machine (idle, requirements-gathering, design, development, testing, bug-fix, release, completed, stopped, failed) with persisted JSON state on disk.
  • Artifact Registry: Versioned artifact storage with auto-incrementing versions (v001, v002, ...), metadata tracking, and ZIP export for all artifact types.
  • Project Workspace Isolation: Per-project isolated working directories with Git bare repos for version-controlled artifact storage.
  • Observer Agent: Parallel daemon thread for log tailing, LLM-based log analysis, and adversarial feedback generation with file-locking for concurrent safety.
  • Bug-Fix Loop: Unbounded iterative fix-test cycle that continues until all tests pass AND PM approves.
  • Pipeline Run Modes: Single-cycle, continuous (configurable duration, default 3h), and hourly execution modes.
  • PM Checkpoint System: Human-in-the-loop gating with configurable checkpoints between each pipeline stage, feedback submission, and work-complete signaling.
  • REST API (57 endpoints): Full CRUD for projects, agents, components, artifacts, Docker containers; pipeline lifecycle management; real-time SSE event streams.
  • WebSocket Services: Terminal WebSocket on port 5759 for browser-based shell access; Docker Exec WebSocket on port 5760 for per-container interactive terminals.
  • Auth Integration: JWT bearer token authentication via external AuthEngine with local login fallback and service-to-service API key support.
  • Component System: Pluggable agent components with model fallback chain (primary → fallback models) and exponential backoff retry.
  • Heartbeat Monitoring: Periodic health monitoring with 30-second failure detection and daily rotating file logging.
  • Frontend SPA (React + Vite): Full-featured dashboard with project management, pipeline monitoring, artifact browser, review/checkpoint UI, log viewer, and Docker management.

Bug Fixes

  • Initial release — no prior bug fixes.

Breaking Changes

  • N/A — initial release.

Deprecations

  • N/A — initial release.

2. Deployment Summary

Architecture Overview

Project.superMindmap is deployed as a single-node Docker container running all backend services. The stack comprises:

  • FastAPI application serving REST API (port 5758), WebSocket Terminal (port 5759), and Docker Exec WebSocket (port 5760)
  • Python 3.11 runtime with async Uvicorn workers
  • SQLite/JSON-on-disk persistence — no RDBMS dependency
  • Git bare repos for version-controlled artifact storage
  • React + Vite frontend (port 5173, runs separately in development)

Dockerfile Reference

The deployment uses a python:3.11-slim base image with the following build stages:

FROM python:3.11-slim
WORKDIR /app
# System dependencies: git, curl
# Python dependencies from requirements.txt (fastapi, uvicorn, httpx, docker, pydantic)
# Application code copied from backend/
EXPOSE 5758 5759 5760
CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "5758", "--workers", "4"]

Runtime Dependencies

Dependency Version Purpose
fastapi >=0.104.0 HTTP framework with async support
uvicorn >=0.24.0 ASGI server (4 workers)
httpx >=0.25.0 Async HTTP client for AuthEngine
docker >=6.1.0 Docker SDK for container lifecycle
pydantic >=2.0.0 Data validation

Environment Requirements

  • Runtime: Docker (any platform) or Python 3.10+ natively
  • Disk: Sufficient space for projects/, bare_repos/, logs/, and artifacts/ directories
  • Network: Ports 5758, 5759, 5760 must be available
  • Optional: AuthEngine service on port 8000 for JWT auth; Docker daemon for container features

Data Directory Structure (created at runtime by setup.sh)

/data/
├── projects/         # Project workspaces with isolation
├── logs/             # Daily rotating execution logs
└── artifacts/        # Versioned artifact storage

3. Release Notes

3.1 What's New in 1.0.0

Project.superMindmap is the first stable release of the Terra-powered AI-driven mindmap generation pipeline. This release establishes the foundational multi-agent orchestration platform capable of autonomously producing software artifacts through a structured pipeline.

Key Capabilities:

  1. End-to-End Pipeline: From requirements to release build, the system orchestrates four specialized AI agents in sequence, producing versioned, auditable artifacts at each stage.
  2. Human-in-the-Loop: Product Manager checkpoints between every stage allow human review, feedback injection, and approval before proceeding.
  3. Self-Healing Bug-Fix Loop: When tests fail, the system automatically re-enters development with the failing test report as context, iterating until all tests pass.
  4. Real-Time Visibility: SSE event streams, heartbeat monitoring, and rotating logs provide full observability into pipeline execution.
  5. Project Isolation: Each project operates in its own workspace with a dedicated Git bare repo, ensuring no cross-project state contamination.

3.2 Artifact Types Produced

Artifact Producer Description
requirements-spec Product Manager Functional and non-functional requirements
ui-design-spec Designer UI/UX design specification
technical-design Developer Architecture and technical design document
source-code Developer Implemented source code
test-cases QA Engineer Test case definitions
test-report QA Engineer Test execution results
deployment-package Developer Deployable build artifacts
release-build Developer Final release build notes

3.3 Pipeline Execution Modes

  • Single Cycle: POST /api/v1/projects/{id}/pipeline/start — One full pass through all stages.
  • Continuous: POST /api/v1/projects/{id}/pipeline/start-continuous — Loops for a configurable duration (default 3 hours), re-reading latest state each iteration.
  • Hourly: POST /api/v1/projects/{id}/pipeline/start-hourly — Single pass, repeats every hour.

4. Known Issues and Limitations

Functional Limitations

# Issue Impact Workaround
1 Single-node architecture only No horizontal scaling; all services run on one machine. Scale vertically. Multi-node support deferred to V2.0.
2 No RDBMS — JSON-on-disk only Query capabilities limited; no indexing; no concurrent write safety beyond file locking. Acceptable for single-user/small-team usage.
3 Unbounded bug-fix loop Pipeline could theoretically loop indefinitely if tests never pass or PM never approves. Manual pipeline stop via POST /pipeline/stop.
4 SSE stream not persisted Client reconnection loses event history; full state must be re-fetched via GET /pipeline/status. Client-side buffering or persistence in V2.0.
5 Agent execution timeout LLM tasks default to 900s timeout. Very large artifacts may hit this limit. Increase timeout.llm_task_seconds in config.json.
6 Feedback history capped at 100 entries Older feedback entries are evicted via FIFO. Export feedback history before reaching cap.

Security Considerations

# Issue Severity Status
1 TLS not enforced in development mode Medium Requires reverse proxy (nginx) in production
2 CORS wide open (*) in V0.5.x Low Acceptable for development; tighten for production
3 AuthEngine is an external dependency Medium Pipeline runs without it (local login fallback)

Performance Constraints

Metric Limit Notes
Concurrent pipelines 10 Single-node threading limit
Managed projects 50 Filesystem inode limits
Repository size 1 GB Git operation latency threshold
API rate limit 100 req/min/user Configurable

5. Post-Release Monitoring Plan

5.1 Health Checks

Endpoint Interval Expected Response
GET /api/v1/health 30s {"status": "healthy", "service": "terra-api", "port": 5758}

5.2 Key Metrics to Monitor

Metric Source Alert Threshold
API response time Application logs > 5s p95
Pipeline iteration count Pipeline status > 10 iterations without completion
Bug-fix loop iterations Pipeline status > 5 consecutive fix attempts
Agent execution timeout Error logs Any timeout event
Disk usage (projects/) System monitoring > 80% capacity
Heartbeat failure count Heartbeat logs > 3 consecutive failures

5.3 Logging

  • Location: logs/terra-YYYYMMDD.log (daily rotation)
  • Format: Structured JSON logs with timestamps, severity, module, and message
  • Retention: 30 days (configurable via log rotation settings)
  • Key Log Streams:
    • GET /api/v1/logs/stream — SSE real-time log stream
    • GET /api/v1/projects/{id}/logs — Project-specific logs

5.4 Alerting

  • Heartbeat failure: Observer Agent detects and records failure within 30 seconds
  • Pipeline stall: No stage transition within configured timeout
  • Agent error: Structured error reports with error_type, suggested_action, and agent context
  • Disk space warning: Manual monitoring via system tools

5.5 Backup Strategy

  1. Git bare repos (bare_repos/) — All artifacts version-controlled; restore any version via git revert
  2. Project state (projects/) — JSON state files; back up entire directory tree
  3. Recovery procedure: Restore projects/ + bare_repos/ → Restart services → Pipelines resume from last persisted state

6. Quick-Start Deployment Command

Docker Deployment (Production)

# Build the image
docker build -t terra-supermindmap:1.0.0 -f backend/Dockerfile .

# Run the container
docker run -d \
  --name terra-supermindmap \
  -p 5758:5758 \
  -p 5759:5759 \
  -p 5760:5760 \
  -v /data/projects:/app/projects \
  -v /data/logs:/app/logs \
  -v /data/artifacts:/app/artifacts \
  -v /data/bare_repos:/app/bare_repos \
  -e AUTHENGINE_API_KEY="" \
  -e OPENCODE_SERVER_URL="http://localhost:4096" \
  --restart unless-stopped \
  terra-supermindmap:1.0.0

Native Deployment (Development)

# Prerequisites: Python 3.10+, Node.js 18+, Git 2.0+
chmod +x scripts/start.sh
./scripts/start.sh

Verify Deployment

# Health check
curl http://localhost:5758/api/v1/health

# API documentation
curl http://localhost:5758/api/v1/docs

Directory Setup (if not using Docker volumes)

# Run setup.sh to create required directories
chmod +x scripts/setup.sh
./scripts/setup.sh

End of Release Build Notes — Version 1.0.0