Skip to content

Commit 853f553

Browse files
OgeonX-AiAitomates
OgeonX-Ai
and
Aitomates
authored
docs: connect NO-AZURE-deploy-lock context in README + add docs-as-code wiki tree (#13)
- README: explicit paragraph tying the existing no-deploy claim to the workspace-wide NO-AZURE-deploy hard lock and cas-platform's bicep-ready-but-not-deployed status; freshness footer - wiki: Home, Architecture (request flow + deploy-lock posture), Operations, Decisions - Adds codex:generate-image placeholder per docs/VISION.md house style Co-authored-by: Kim Harjamäki <kim.harjamaki@prosimo.fi>
1 parent a850e68 commit 853f553

5 files changed

Lines changed: 185 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,12 @@ It runs a useful deterministic workflow locally, emits canonical [`cas-contracts
1818

1919
This project does not use Classic Assistants APIs and does not deploy Azure resources.
2020

21+
Azure deployment is locked workspace-wide until a future milestone (the CAS workspace's
22+
NO-AZURE-deploy hard lock). `cas-platform`, the deployment target this project's interface is
23+
designed for, is maintained "bicep-ready" (linted, parameterized, pinned) per Phase 33 but is not
24+
itself deployed. This repository's Foundry Next Gen adapter is exercised only through local runs
25+
and CI's Docker health-check smoke test — never a live Azure deploy.
26+
2127
## Run Locally
2228

2329
Prerequisites: Python 3.12 and PowerShell.
@@ -72,3 +78,9 @@ The image runs as a non-root user, listens on port `8080`, and provides `/health
7278
## Security
7379

7480
Report vulnerabilities through GitHub private vulnerability reporting. Do not include credentials or sensitive prompt data in issues.
81+
82+
## Wiki
83+
84+
For a docs-as-code wiki (Home, Architecture, Operations, Decisions), see [`docs/wiki/`](docs/wiki/Home.md).
85+
86+
<!-- docs-verified: 57c21b03a48332728105b72a90e8e89deda409af 2026-07-08 -->

‎docs/wiki/Architecture.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Architecture
2+
3+
`cas-reference-product` implements a strictly typed request/response boundary using canonical
4+
`cas-contracts` data structures, with interchangeable local and Foundry Next Gen agent adapters
5+
behind the same `WorkflowAgentService` interface.
6+
7+
```mermaid
8+
flowchart TD
9+
Client[Client] -->|"POST /api/v1/workflows\nPromptEnvelope"| FastAPI["FastAPI Server\napp.py"]
10+
FastAPI --> Middleware["W3CTraceContextMiddleware\ntelemetry.py"]
11+
Middleware --> Router[Workflow Router]
12+
Router --> Orchestrator["WorkflowOrchestrator\nworkflow.py"]
13+
Orchestrator --> AgentService{"WorkflowAgentService\nworkflow.py"}
14+
AgentService -->|Local Config| LocalAgent[LocalWorkflowAgentService]
15+
AgentService -->|Foundry Config| FoundryAgent[FoundryWorkflowAgentService]
16+
FoundryAgent -->|Managed Identity| AzureAuth["DefaultAzureCredential\nidentity.py"]
17+
AzureAuth -->|Responses API| AzureAI[Azure AI Projects API]
18+
AzureAI -->|Invoke Agent| FoundryNextGen[Foundry Next Gen Agent]
19+
LocalAgent -->|Deterministic Output| Orchestrator
20+
FoundryAgent -->|Agent Output| Orchestrator
21+
Orchestrator -->|"RunEvent"| Router
22+
Router -->|200 OK| Client
23+
```
24+
25+
<!-- codex:generate-image prompt="A single reference workbench with two interchangeable adapter modules plugged into the same socket, one glowing green labeled Local (deterministic, offline), the other labeled Foundry with a dotted cable running to a distant locked cloud icon; isometric, enterprise blue/graphite palette" style="isometric, enterprise, clean" replaces="mermaid-above" -->
26+
27+
## Components
28+
29+
- **FastAPI web layer (`app.py`)** — exposes `/api/v1/workflows`, `/health/live`,
30+
`/health/ready`; manages OpenTelemetry spans via `PromptEnvelope.correlationId`.
31+
- **Telemetry (`telemetry.py`)** — `W3CTraceContextMiddleware` parses and propagates
32+
`traceparent`/`tracestate` headers.
33+
- **Workflow Orchestrator (`workflow.py`)** — wraps agent execution, emits canonical `RunEvent`
34+
data points (`workflow.started`, `workflow.completed`, `workflow.failed`).
35+
- **Workflow Agent Service** — the application boundary for AI logic, with local (deterministic)
36+
and Foundry Next Gen (managed-identity, Responses API) adapters behind one interface.
37+
38+
## Deployment lock (NO-AZURE posture)
39+
40+
This project does not use Classic Assistants APIs and does not deploy Azure resources. Azure
41+
deployment is locked workspace-wide until a future milestone is deliberately reached — no
42+
service under this workspace may be provisioned or deployed from here. `cas-platform`, the
43+
Container Apps target this repo's interface (`deployment/cas-platform.interface.yaml`) is built
44+
for, is maintained "bicep-ready" (linted, parameterized, pinned per Phase 33) but is not itself
45+
deployed. The Foundry Next Gen adapter in this repo is exercised only through local runs and
46+
CI's Docker health-check smoke test (`ci.yml`'s `docker` job) — never a live Azure deploy.
47+
48+
## Reference-product contract
49+
50+
Deploys as a Linux container image on port `8080` (internal ingress by default), exposing
51+
`/health/live` and `/health/ready`. Workload configuration is non-secret and injected at
52+
runtime; Application Insights connection strings are injected securely from the platform's
53+
observability module outputs.
54+
55+
<!-- docs-verified: 57c21b03a48332728105b72a90e8e89deda409af 2026-07-08 -->

‎docs/wiki/Decisions.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Decisions
2+
3+
This repo's `.planning/` tree holds `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and
4+
`STATE.md` but no phase SUMMARY files as of this writing — the project is tracked at the
5+
requirements/roadmap level rather than through executed phase plans in this repo's checkout.
6+
7+
- [`.planning/PROJECT.md`](../../.planning/PROJECT.md) — goals and requirements
8+
- [`.planning/ROADMAP.md`](../../.planning/ROADMAP.md) — roadmap
9+
- [`.planning/REQUIREMENTS.md`](../../.planning/REQUIREMENTS.md) — requirements traceability
10+
- [`docs/case-study-evidence.md`](../case-study-evidence.md) — immutable golden-path case-study
11+
evidence, the closest artifact this repo has to a decision/evidence record
12+
13+
## Architecture Decision Records (`docs/adr/`)
14+
15+
[`docs/adr/`](../adr/README.md) is the formal ADR home for this repo. No sequentially-numbered
16+
ADR files have been recorded yet as of this writing — the directory holds only the governance
17+
README.
18+
19+
<!-- docs-verified: 57c21b03a48332728105b72a90e8e89deda409af 2026-07-08 -->

‎docs/wiki/Home.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# cas-reference-product Wiki
2+
3+
`cas-reference-product` is the public v0.1 reference application for the Coding Autopilot
4+
System and Microsoft Foundry Next Gen Agents. It runs a deterministic workflow locally, emits
5+
canonical `cas-contracts` v0.1 lifecycle events, and includes a Foundry adapter that invokes a
6+
Next Gen agent through the project Responses client. It is designed for the Container Apps and
7+
managed-identity boundary supplied by `cas-platform`.
8+
9+
## Deployment status: local-first, no live Azure deploy
10+
11+
This project does not use Classic Assistants APIs and does not deploy Azure resources. See
12+
[Architecture](Architecture.md) for the full NO-AZURE-deploy-lock statement.
13+
14+
## Quickstart
15+
16+
```powershell
17+
./scripts/validate.ps1
18+
./scripts/run-local.ps1
19+
```
20+
21+
```powershell
22+
Invoke-RestMethod `
23+
-Method Post `
24+
-Uri http://127.0.0.1:8080/api/v1/workflows `
25+
-ContentType application/json `
26+
-InFile examples/prompt-envelope.json
27+
```
28+
29+
The local backend returns deterministic output and two canonical lifecycle events. It requires
30+
no Azure account.
31+
32+
## Where to go next
33+
34+
- [Architecture](Architecture.md) — request flow, local vs. Foundry adapters, deploy-lock posture
35+
- [Operations](Operations.md) — verified run/test/CI commands
36+
- [Decisions](Decisions.md) — index of recorded architectural decisions
37+
38+
<!-- docs-verified: 57c21b03a48332728105b72a90e8e89deda409af 2026-07-08 -->

‎docs/wiki/Operations.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Operations
2+
3+
## Local run
4+
5+
```powershell
6+
./scripts/validate.ps1
7+
./scripts/run-local.ps1
8+
```
9+
10+
Submit `examples/prompt-envelope.json` to `POST /api/v1/workflows`. Liveness is `/health/live`;
11+
readiness is `/health/ready`.
12+
13+
Hardened local container run:
14+
15+
```powershell
16+
docker run --rm --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges `
17+
-p 8080:8080 cas-reference-product:local
18+
```
19+
20+
## CI gate (`.github/workflows/ci.yml`)
21+
22+
The `validate` job (Python 3.12, `pip install -e ".[dev]"`) runs on every push/PR to `main`:
23+
24+
```bash
25+
python -m ruff check .
26+
python -m mypy
27+
python -m pytest tests/test_contract_registry.py -q --tb=short -o addopts=""
28+
python -m pytest
29+
python -m cas_reference_product.evidence
30+
```
31+
32+
The contract-compatibility test is a consumer-side gate: it fails red if the pinned
33+
`cas-contracts` version or the vendored v0.1 schema release drifts from what the Pydantic
34+
models emit.
35+
36+
The `docker` job builds a Linux/amd64 image, runs it locally with `ENVIRONMENT=local` and
37+
`WORKFLOW_BACKEND=local`, health-checks `/health/live` and `/health/ready`, and — only on push
38+
to `main` — pushes to GHCR. There is no coverage-percentage gate in this repo's CI as of this
39+
writing; the gate is ruff/mypy/pytest/evidence pass-fail, not a coverage threshold.
40+
41+
## Foundry mode
42+
43+
Set `ENVIRONMENT` to `dev`/`test`/`prod`, `WORKFLOW_BACKEND=foundry`, and the non-secret
44+
`FOUNDRY_PROJECT_ENDPOINT`/`FOUNDRY_AGENT_NAME`. The Azure-hosted workload uses its
45+
system-assigned managed identity; no API keys or client secrets are configured. Readiness fails
46+
until required Foundry identifiers are present; Foundry connectivity is exercised only by
47+
workflow requests, not probes.
48+
49+
## Platform handoff (validation only, no deploy)
50+
51+
```powershell
52+
az bicep build --file infra/main.bicep
53+
az deployment group what-if --resource-group <resource-group> --template-file infra/main.bicep --parameters foundryProjectResourceId=<resource-id>
54+
```
55+
56+
Deployment is intentionally not performed by repository validation — consistent with the
57+
workspace NO-AZURE-deploy lock. Build a Linux AMD64 image and pass its immutable image reference
58+
to the `containerImage` parameter of `cas-platform`; review
59+
`deployment/cas-platform.interface.yaml` before platform changes.
60+
61+
<!-- docs-verified: 57c21b03a48332728105b72a90e8e89deda409af 2026-07-08 -->

0 commit comments

Comments
 (0)