# Buzen ESB Documentation Site

This site is the implementation guide for Buzen ESB users, operators, and AI agents.
For strict source-of-truth alignment, use source-synced artifacts first.

## Source alignment snapshot
- Snapshot JSON: reference/source/source-snapshot.json
- Endpoint map (JSON): reference/source/management-endpoints.json
- Endpoint map (Markdown): reference/source/management-endpoints.md

## Primary entry points
- Home: index.html
- Getting started: pages/getting-started.html
  - Prerequisites: pages/getting-started.html#prereq
  - Build: pages/getting-started.html#build
  - Run (JAR): pages/getting-started.html#run
  - Run (Docker): pages/getting-started.html#docker
  - First login: pages/getting-started.html#login
  - First app deploy: pages/getting-started.html#first-app
  - Verification: pages/getting-started.html#verify
- Runtime model: pages/setup-and-runtime.html
  - Embedded components: pages/setup-and-runtime.html#components
  - Runtime home: pages/setup-and-runtime.html#home
  - Startup sequence: pages/setup-and-runtime.html#startup
  - Route loading: pages/setup-and-runtime.html#loading
  - App lifecycle: pages/setup-and-runtime.html#app-lifecycle
  - Route lifecycle: pages/setup-and-runtime.html#route-lifecycle
  - Ingress validation: pages/setup-and-runtime.html#ingress
- Configuration: pages/configuration.html
  - Configuration model: pages/configuration.html#model
  - Critical settings: pages/configuration.html#critical
  - Security and TLS: pages/configuration.html#security
  - Route settings: pages/configuration.html#routes
  - Resilience: pages/configuration.html#resilience
  - Monitoring: pages/configuration.html#monitoring
  - Env variable mappings: pages/configuration.html#profiles
  - Production example: pages/configuration.html#examples
  - Go-live checklist: pages/configuration.html#checklist
- Deployment: pages/deployment.html
  - Deployment model: pages/deployment.html#overview
  - .bar archive layout: pages/deployment.html#archive
  - Manifest spec: pages/deployment.html#manifest
  - Deployment methods: pages/deployment.html#methods
  - Lifecycle operations: pages/deployment.html#lifecycle
  - Versioning and rollback: pages/deployment.html#versioning
  - Hot deploy: pages/deployment.html#hotdeploy
  - Validation rules: pages/deployment.html#validation
- YAML authoring: pages/yaml-authoring.html
  - Canonical route shape: pages/yaml-authoring.html#canonical
  - Authoring rules: pages/yaml-authoring.html#rules
  - Single-route constraints: pages/yaml-authoring.html#single
  - IDs and collisions: pages/yaml-authoring.html#ids
  - Ingress safety: pages/yaml-authoring.html#ingress
  - Variables: pages/yaml-authoring.html#variables
  - Reference patterns: pages/yaml-authoring.html#patterns
  - Pre-deploy checklist: pages/yaml-authoring.html#checklist
- Flow designer nodes: pages/flow-designer-nodes.html
  - Designer model: pages/flow-designer-nodes.html#overview
  - Full node catalog: pages/flow-designer-nodes.html#catalog
  - Recommended patterns: pages/flow-designer-nodes.html#patterns
  - Import/export limits: pages/flow-designer-nodes.html#limits
- Connectors/components: pages/connectors-and-components.html
  - Built-in connectors: pages/connectors-and-components.html#builtin
  - URI patterns: pages/connectors-and-components.html#uris
  - Configuration keys: pages/connectors-and-components.html#config
  - Health behavior: pages/connectors-and-components.html#health
  - Custom connector SPI: pages/connectors-and-components.html#spi
  - Module hierarchy: pages/connectors-and-components.html#modules
- Management API: pages/management-api.html
  - Base path and auth: pages/management-api.html#base
  - Response envelope: pages/management-api.html#envelope
  - Role matrix: pages/management-api.html#roles
  - Endpoint catalog: pages/management-api.html#catalog
  - Automation workflows: pages/management-api.html#workflows
  - Schema contracts: pages/management-api.html#schemas
  - Error handling: pages/management-api.html#errors
- Security/policies: pages/security-and-policies.html
  - Authentication model: pages/security-and-policies.html#auth
  - Authorization roles: pages/security-and-policies.html#roles
  - Ingress boundaries: pages/security-and-policies.html#ingress
  - TLS configuration: pages/security-and-policies.html#tls
  - Policy framework: pages/security-and-policies.html#policies
  - Secrets handling: pages/security-and-policies.html#secrets
  - Hardening checklist: pages/security-and-policies.html#hardening
- Operations/troubleshooting: pages/operations-troubleshooting.html
  - Health checks: pages/operations-troubleshooting.html#health
  - Logs and traces: pages/operations-troubleshooting.html#logs
  - Metrics and alerts: pages/operations-troubleshooting.html#metrics
  - Backup and restore: pages/operations-troubleshooting.html#backup
  - Incident runbook: pages/operations-troubleshooting.html#incidents
  - Common failures: pages/operations-troubleshooting.html#failures
- AI integration guide: pages/ai-bot-guide.html
  - Non-negotiable rules: pages/ai-bot-guide.html#rules
  - Output profiles: pages/ai-bot-guide.html#profile
  - Deterministic sequences: pages/ai-bot-guide.html#sequences
  - Schema validation: pages/ai-bot-guide.html#validation
  - Error branching: pages/ai-bot-guide.html#errors
  - Prompt templates: pages/ai-bot-guide.html#prompts
- Samples: pages/samples.html
  - Quick deploy sample: pages/samples.html#quick
  - Pattern library: pages/samples.html#patterns
  - Production blueprint: pages/samples.html#bar
  - API payload samples: pages/samples.html#api
  - CI/CD script: pages/samples.html#cicd

## Machine-readable contracts
- Source snapshot: reference/source/source-snapshot.json
- Management endpoint map: reference/source/management-endpoints.json
- Search index: search-index.json

## Compatibility profiles (site-maintained)
- Manifest profile schema: reference/docs/schemas/buzen-archive-manifest.schema.json
- Route upsert profile schema: reference/docs/schemas/app-route-upsert-request.schema.json
- Route duplicate profile schema: reference/docs/schemas/app-route-duplicate-request.schema.json
- Flow designer profile schema: reference/docs/schemas/buzen-flow-designer-route.schema.json

## Source references (synced markdown)
- Source contract notes: reference/source/README.md
- Project README: reference/README.md
- Docker Ops Runbook: reference/docker-docs/ops-runbook.md
- Docker Release Notes: reference/docker-docs/release-notes-1.0.100.md

## Guidance for agents
- Read `reference/source/source-snapshot.json` first for source commit/version context.
- Use `reference/source/management-endpoints.json` for static endpoint discovery.
- Prefer runtime OpenAPI (`/api-docs` and `/swagger-ui.html`) when a live instance is available.
- Authenticate first for protected API calls.
- Use `/api/v1` unless management base path is overridden.
- Parse `ApiResponse` envelopes for most endpoints; policy endpoints currently return raw DTOs.
- Keep app route create/update payloads single-route and deterministic.
- Avoid reserved ingress prefixes (`/api/v1`, `/actuator`, `/console`, `/ws`, `/api-docs`, `/swagger-ui`, `/v3/api-docs`).