Metacore Stack — Meta-Platform (MVP)

Technical Report: See ci/tech-report.md for detailed build status, test results, and pipeline observability.

Mono-repo with:

• server-dotnet/ — Room Host (.NET 8 + SignalR) + RoomOperator
• mcp-ts/ — MCP servers in TypeScript
• apps/operator-dashboard/ — Operator Dashboard (Vite/React)
• tools/integration-api/ — Integration API (Express/TypeScript)
• ui/ — Minimal UI (Next.js) [optional in this cycle]
• schemas/ — Base JSON Schemas + examples + AJV validation
• infra/ — docker-compose for local environment
• docs/ — Documentation (see Table of Contents)

Port Configuration

All components use standardized ports for easy integration:

• RoomServer: 40801
• RoomOperator: 40802
• Integration API: 40901
• Dashboard UI: 5173

See PORT_CONFIGURATION.md for detailed setup and configuration.

Quickstart

# 0) verify environment (optional but recommended)
make verify-environment

# 1) prepare tools
make bootstrap

# 2) start example MCP servers
make mcp-up

# 3) run Room Host
make run-server

# 4) validate schemas
make schemas-validate

CI/CD Pipeline & Development Workflow

Local Development Commands

# Build all projects
npm run build        # Node/TypeScript projects
dotnet build -c Release server-dotnet/RoomServer.sln  # .NET projects

# Run tests
npm test            # Schemas + contract validation
dotnet test server-dotnet/RoomServer.sln  # .NET tests

# Code quality
npm run lint        # ESLint
npm run format      # Prettier check
npm run format:fix  # Prettier write
dotnet format server-dotnet/RoomServer.sln  # .NET format

# Type checking
npm run typecheck   # TypeScript

Observability & Testing

# Test SSE heartbeat endpoint
npm run smoke:stream

# Validate contracts
npm run test:contracts

# Start Integration API with structured logging
cd tools/integration-api
npm run dev

Key Features:

• ✅ Structured JSON logging with traceId/runId
• ✅ SSE endpoints with heartbeat monitoring
• ✅ OpenAPI 3.1 specification with validation
• ✅ Contract-based testing for all schemas
• ✅ Reproducible builds with pinned SDK versions

See ci/tech-report.md for detailed technical documentation.

RoomOperator Integration Testing

Test the complete integration between RoomOperator and RoomServer:

Enhanced Integration Tests (Recommended)

The enhanced integration test system provides comprehensive validation with artifact collection, performance metrics, and detailed tracing:

cd server-dotnet/operator/scripts
./run-integration-enhanced.sh

Features:

• Automated service orchestration with readiness checks
• Artifact collection in .artifacts/integration/{timestamp}/
• Performance metrics (P50/P95 latency, success rates)
• Structured trace logging (NDJSON format)
• Comprehensive JSON and text reports

See Enhanced Integration Testing Guide for details.

Quick Automated Test

# Quick automated test (builds, starts services, runs tests)
cd server-dotnet/operator/scripts
./run-integration-test.sh

Manual Component Testing

# Or run components manually:
# Terminal 1: Start RoomServer
cd server-dotnet/src/RoomServer
dotnet run

# Terminal 2: Start RoomOperator
cd server-dotnet/operator
dotnet run

# Terminal 3: Run test client
cd server-dotnet/operator/test-client
npm install
npm run test:all

Available test scenarios:

• npm run test:basic - Complete happy path (entities → artifacts → policies)
• npm run test:basic-enhanced - Enhanced basic flow with trace logging
• npm run test:error - Error handling and validation
• npm run test:stress - Performance and load testing

Documentation:

• Enhanced Integration Testing - Comprehensive test system with artifacts and metrics
• Integration Guide - Complete API reference, communication flows, and error handling
• Testing Guide - Detailed testing instructions and troubleshooting
• RoomOperator Docs - Operator architecture and usage
• Test Client README - Test client usage and customization

Structure and Conventions

• .NET 8, Node 20, pnpm 9
• Conventional Commits
• CI: build + lint + test + schema validation

Flow Validation

• Layer 3 Flows: ✅ Validated and tested (see report)
  • Flow 3.1: Room Creation (5 tests)
  • Flow 3.2: Entity Entry (8 tests)
  • Additional scenarios: 2 tests
  • 15 automated tests, 100% passing

Documentation

📚 Quick Navigation

• Table of Contents - Complete documentation index organized by category
• Glossary - Domain terms and concepts reference
• Getting Started - Quick start guide for the operator dashboard
• Development Setup - Development environment setup
• Port Configuration - Port assignments and configuration
• Testing Guide - Comprehensive testing instructions
• Integration Guide - RoomOperator and RoomServer integration

🏗️ Architecture & Decisions

• Architecture Decisions (ADRs) - Architecture Decision Records
  • ADR Template - Template for new ADRs
• Concept Definition - Core concepts and architecture
• Room Operator - Operator architecture and usage
• MCP Connection Behavior - MCP connection patterns

🤖 Agent Resources

Resources for AI coding agents and automation:

• Agent Briefs - Guide for writing focused task briefs
• Agent Playbooks - Guide for multi-step workflows
• Templates - Brief, playbook, and context card templates

📖 Component Context

Quick-start guides for key components:

• Operator Dashboard Context - Dashboard component guide
• Integration API Context - API component guide

📋 Operational Guides

• Runbooks - Operational procedures and troubleshooting
• Interfaces - Machine-readable API contracts and specifications

📊 Reports & Analysis

• Layer 3 Flow Validation - Flow validation results
• Schema-RoomServer Alignment - Alignment report
• Documentation Curation Report - Documentation organization summary

🗂️ Repository Structure

metacore-stack/
├── apps/
│   └── operator-dashboard/     # Operator Dashboard (Vite/React)
│       └── CONTEXT.md          # Component context card
├── tools/
│   └── integration-api/        # Integration API (Express/TypeScript)
│       └── CONTEXT.md          # Component context card
├── server-dotnet/
│   ├── src/RoomServer/         # Room Server (.NET 8)
│   └── operator/               # Room Operator
├── docs/                       # Active documentation
│   ├── TOC.md                  # Table of Contents
│   ├── glossary.md             # Glossary of terms
│   ├── curation-report.md      # Curation report
│   ├── docs.manifest.json      # Documentation inventory
│   ├── _adr/                   # Architecture Decision Records
│   ├── _deprecated/            # Deprecated docs (historical reference)
│   ├── _archive/               # Archived docs
│   ├── interfaces/             # API contracts and specifications
│   ├── runbooks/               # Operational runbooks
│   └── agent/                  # Agent scaffolding
│       ├── briefs/             # Brief writing guide
│       ├── playbooks/          # Playbook writing guide
│       └── templates/          # Document templates
├── schemas/                    # JSON Schemas (domain objects)
├── configs/                    # Configuration files
│   └── schemas/                # Configuration schemas
├── infra/                      # Infrastructure (docker-compose)
└── scripts/                    # Utility scripts

🤝 Contributing

See CONTRIBUTING.md for:

• Commit conventions (Conventional Commits)
• Pull request requirements
• Build and test expectations
• Schema versioning guidelines

License

MIT (adjust as needed)