AIITOps

AIITOps is an enterprise platform for running AI agents that plan, build, test, deploy, document, and operate customer applications through a governed control plane.

This repository is the control-plane foundation. It currently contains the Phase 0 bootstrap assets:

• project requirements and PRD
• repo standards and contribution workflow
• shared agent instruction baseline
• Python project metadata managed with uv
• local setup automation for the first development environment

Phase 1 adds:

• modular control-plane service architecture
• observability and secure configuration foundations
• Terraform scaffolding for Azure dev environments
• CI/CD workflows for validation and non-production deployment

Phase 2 adds:

• backend authentication modes for development and Microsoft Entra
• tenancy models for organizations, projects, and scoped memberships
• role-to-feature authorization checks
• approval-aware policy evaluation and audit tracking
• governed agent identity cataloging for managed-identity planning

Phase 3 adds:

• control-plane domain records for apps, environments, resources, events, and notifications
• a workflow engine with manual and scheduled definitions
• task state transitions with waiting, retry, and resume behavior
• notification routing for workflow and approval activity
• event capture with unusual-event filtering and archival hooks
• customer resource topology and dependency graph APIs

Phase 4 adds:

• a governed agent registry for the first six core agents
• context assembly from workflows, app metadata, requirements, and asset-library guidance
• Azure Foundry-compatible model access with safe preview-mode fallback
• policy-aware agent invocation with approval blocking for sensitive runs
• structured agent outputs, branch-level plans, and agent run history APIs

Phase 5 adds:

• GitHub-linked repository records for seeded applications
• backlog synchronization from Project Manager plans into GitHub-style work items
• assignment flows for humans and agents
• branch creation using Coding Agent branch proposals
• pull request creation with workflow and agent metadata
• testing evidence attachment and release-gate summaries for review

Phase 6 adds:

• a Flutter human UI under apps/control_plane_ui
• a web-first responsive shell for dashboard, workflows, inbox, delivery, and conversation views
• live control-plane API integration with deterministic demo-data fallback
• persona switching for Project Manager, Approver, and Local Admin workflows
• Flutter validation in both local tooling and CI

Phase 7 adds:

• a customer-plane application factory service for one reference MVP archetype
• requirement capture, backlog generation, repo registration, and scaffold planning in one flow
• per-app dev environment planning and Azure resource-topology registration
• automatic use of Project Manager, Coding, Testing, and Author agent runs inside the factory flow
• factory APIs for archetypes and run history

Phase 8 adds:

• governance review services for security, budget, operations, and nightly health bundles
• expanded agent coverage for Security, Budget, Operations, UserAdmin, Versioning, and Cloud Admin
• approval-aware admin and cloud change planning
• automatic execution of the nightly health workflow into a reviewable governance record
• governance APIs for findings, budget reviews, and stored nightly health-check runs

Phase 9 adds:

• persistent regression suites and readiness snapshots under debug/
• provider-readiness records for Azure-active and AWS/GCP interface-ready expansion
• platform testing-readiness reporting across docs, automation, governance, and artifacts
• release-readiness reporting for pull requests using evidence, approvals, governance, and regression signals
• a final pre-testing API surface that prepares the platform state for QA handoff

Current Scope

The initial implementation is Azure-first and currently centers on:

• a Flutter-based human UI
• Python backend services
• Microsoft Agent Framework orchestration
• Azure Foundry model usage
• GitHub-based planning and delivery workflows
• one reference customer application factory flow
• governed operations, security, budget, and admin review flows

Quick Start

1. Bootstrap the environment

pwsh -File .\scripts\bootstrap.ps1

1a. Install local Terraform, Flutter, and Flutter-side MCP tooling

pwsh -File .\scripts\install-external-tools.ps1
pwsh -File .\scripts\dev-shell.ps1

2. Activate the virtual environment

.\.venv\Scripts\Activate.ps1

3. Run the starter API

uv run uvicorn aiitops.main:app --reload

4. Run tests

uv run pytest

5. Run the Flutter UI

Set-Location .\apps\control_plane_ui
& ".\.local-tools\flutter\flutter\bin\flutter.bat" run -d chrome

6. Run the full validation suite

pwsh -File .\scripts\validate.ps1

7. Generate a testing handoff package

pwsh -File .\scripts\prepare-testing.ps1 -RunValidation

Repository Layout

docs/          Product docs, ADRs, and design records
apps/          Flutter UI and future human-facing applications
infra/         Infrastructure-as-code and environment definitions
src/           Python source for the control plane
tests/         Automated tests
scripts/       Bootstrap and developer automation
temp/          Local temporary files (ignored)
debug/         Local debug output (ignored)
Reqs/          Source requirements documents

Phase 1 Architecture

• src/aiitops/api: FastAPI app factory, middleware, and routers
• src/aiitops/application: service wiring and dependency container
• src/aiitops/orchestration: orchestration runtime primitives
• src/aiitops/workflows: workflow service foundation
• src/aiitops/policy: approval and policy guard foundations
• src/aiitops/integrations: Azure and GitHub integration boundaries
• src/aiitops/observability: logging and telemetry setup
• src/aiitops_shared: shared contracts and reusable library primitives

Phase 2 Identity Model

• development auth mode uses seeded local users and the optional x-aiitops-user-id header.
• entra auth mode validates bearer tokens against Microsoft Entra signing keys.
• Organizations and projects are access-scoped through memberships and feature mappings.
• Sensitive actions can return require_approval and create approval records before execution.

Key Phase 2 Routes

• GET /api/v1/identity/me
• GET /api/v1/identity/agents
• GET /api/v1/tenancy/organizations
• GET /api/v1/tenancy/organizations/{org_id}/projects
• POST /api/v1/policy/evaluate
• GET /api/v1/policy/approvals
• POST /api/v1/policy/approvals/{approval_id}/decisions
• GET /api/v1/policy/audit

Key Phase 3 Routes

• GET /api/v1/domain/apps
• GET /api/v1/domain/apps/{app_id}
• GET /api/v1/domain/apps/{app_id}/resources
• GET /api/v1/workflows/definitions
• GET /api/v1/workflows/runs
• POST /api/v1/workflows/runs
• GET /api/v1/workflows/runs/{workflow_run_id}
• POST /api/v1/workflows/runs/{workflow_run_id}/tasks/{task_run_id}/transition
• POST /api/v1/workflows/runs/{workflow_run_id}/retry
• POST /api/v1/workflows/runs/{workflow_run_id}/resume
• POST /api/v1/workflows/scheduler/tick
• GET /api/v1/notifications
• POST /api/v1/notifications/{notification_id}/acknowledge
• GET /api/v1/events
• POST /api/v1/events/archive

Key Phase 4 Routes

• GET /api/v1/agents/definitions
• GET /api/v1/agents/definitions/{agent_id}
• POST /api/v1/agents/definitions/{agent_id}/context
• POST /api/v1/agents/definitions/{agent_id}/invoke
• GET /api/v1/agents/runs
• GET /api/v1/agents/runs/{agent_run_id}

Key Phase 5 Routes

• GET /api/v1/github/repositories
• GET /api/v1/github/repositories/{repo_id}
• GET /api/v1/github/repositories/{repo_id}/work-items
• POST /api/v1/github/repositories/{repo_id}/work-items/sync
• POST /api/v1/github/work-items/{work_item_id}/assignments
• GET /api/v1/github/repositories/{repo_id}/branches
• POST /api/v1/github/repositories/{repo_id}/branches
• GET /api/v1/github/repositories/{repo_id}/pull-requests
• POST /api/v1/github/repositories/{repo_id}/pull-requests
• GET /api/v1/github/pull-requests/{pull_request_id}
• POST /api/v1/github/pull-requests/{pull_request_id}/evidence

Phase 6 UI Highlights

• apps/control_plane_ui/lib/src/presentation/control_plane_shell.dart provides the responsive command-deck shell.
• apps/control_plane_ui/lib/src/data/control_plane_repository.dart maps Flutter interactions to the Phase 2-5 backend APIs.
• The UI defaults to the Azure Container App API and can be overridden with AIITOPS_API_BASE_URL for alternate environments.
• When the backend is unavailable, the app falls back to seeded demo data so flows remain reviewable.

Key Phase 7 Routes

• GET /api/v1/factory/archetypes
• GET /api/v1/factory/runs
• GET /api/v1/factory/runs/{factory_run_id}
• POST /api/v1/factory/runs

Phase 7 Factory Highlights

• src/aiitops/factory/service.py orchestrates the MVP factory across workflows, agents, GitHub delivery, Azure planning, and topology registration.
• src/aiitops_shared/models/factory.py defines the archetype, deployment-plan, scaffold, and factory-run contracts.
• The current MVP archetype is a customer service portal built with Flutter Web, FastAPI, and Azure-first infrastructure.
• Creating a factory run registers a new app, seeds a repository/backlog/PR, records deployment artifacts, and exposes the generated app through the existing domain routes.

Key Phase 8 Routes

• GET /api/v1/governance/security/findings
• GET /api/v1/governance/budget/reviews
• GET /api/v1/governance/operations/findings
• GET /api/v1/governance/health-checks

Phase 8 Governance Highlights

• src/aiitops/governance/service.py derives scoped security, budget, and operations signals and stores nightly health-check bundles.
• The nightly wf-nightly-health-check workflow now auto-completes with governance outputs instead of remaining an empty scheduled shell.
• The agent registry now includes governance and admin-focused agents, all enforced through the same policy and approval model as earlier phases.
• Identity posture for the expanded agent set is visible through GET /api/v1/identity/agents.

Key Phase 9 Routes

• GET /api/v1/readiness/providers
• GET /api/v1/readiness/platform
• POST /api/v1/readiness/platform/prepare
• GET /api/v1/readiness/regression-suites
• POST /api/v1/readiness/regression-suites
• GET /api/v1/readiness/snapshots
• POST /api/v1/readiness/snapshots
• GET /api/v1/readiness/releases/{pull_request_id}

Phase 9 Testing-Readiness Highlights

• src/aiitops/readiness/service.py persists regression suites and readiness snapshots to debug/regression-suites and debug/readiness-snapshots.
• scripts/prepare-testing.ps1 generates a local QA handoff pack, including JSON and Markdown summaries in debug/testing-handoffs.
• src/aiitops/readiness/handoff.py provides the CLI entry point for that handoff generation flow.
• POST /api/v1/readiness/platform/prepare runs the platform regression suite, ensures a governance health bundle exists, captures a snapshot, and returns a consolidated readiness report.
• Release-readiness reports evaluate passed evidence, release checkpoints, pending approvals, scoped health-check coverage, and the latest regression suite for the target app.
• Provider readiness is now explicit: Azure is the active implementation and AWS/GCP are represented as interface-ready expansion targets.

Standards

• Security first and least privilege by default
• Reuse the shared asset library before introducing new components
• Keep docs/ and README.md current with every meaningful change
• Use .env locally and never commit secrets
• Prefer cloud services over custom infrastructure when possible
• Do not use mockups in place of working flows

Related Documents

• Product Requirements Document
• Contributing Guide
• Agent Instructions
• UI Operations Runbook
• Customer App Factory Runbook
• Governance Operations Runbook
• Testing Readiness Runbook