Skip to main content

Architecture & Docs Overview

Purpose​

This page describes the unified approach used by the master framework: implement Tools, Agents, and Workflows to solve platform problems, and expose project-specific extensions (K12, TAP) that use those primitives.

High-level philosophy​

  • Unified approach: Problems are solved by composing Tools, Agents, and Workflows. Keep each piece small, testable, and well-documented.
  • Project-specific surfaces: K12 and TAP provide domain-specific tools and workflows that extend the core framework.
  • Project-agnostic components: Examples: Reasoning Engine, Admin tools, database artifacts — document these centrally so they can be reused.

Projects:

Core components:

Database:

Deployment & Azure:

  1. Overview (this page)
  2. Services & Authentication — Managed Identity-first guidance and APIM patterns
  3. Environment variables matrix — Common + per-project (skeleton included below)
  4. Database — ER diagrams, table list, DACPAC deployment flow, migration guidelines
  5. Reasoning Engine — architecture, inputs/outputs, how to run and test locally
  6. Admin tools — debugging tools, health checks, and example workflows
  7. Project pages (K12 & TAP) — tool / workflow docs, test harnesses, and troubleshooting
  8. Templates & checklists — docs templates, authoring checklist, and linting rules

Env-var matrix (skeleton)​

Below is a starter matrix. A dedicated page (architecture/env-vars) holds the full, exportable table and sample .env snippets — see the Environment variables matrix for details.

Common variables

  • AZURE_SQL_CONNECTION_STRING — Connection string used by all services to reach Azure SQL
  • AZURE_INFERENCE_ENDPOINT — Endpoint for tenant-hosted LLM deployments (Managed Identity recommended)
  • AZURE_CONTENT_SAFETY_ENDPOINT — Content Safety endpoint when used
  • AZURE_CONTENT_SAFETY_KEY — Optional: content safety API key (fallback only)
  • AUTH_API_BASE_URL — Base URL for auth API used in tests and local development

Per-project variables (examples)

  • K12: K12_DB_SCHEMA, K12_TEST_SERVER_URL, K12_QUEUE_CONNECTION_STRING
  • TAP: TAP_API_BASE_URL, TAP_QUEUE_NAME, TAP_STORAGE_ACCOUNT

Tip: All env var definitions should indicate: scope (common/project), required/optional, sample value, and short description.

Database docs (summary)​

  • Document schema per project and core schema (Core, Platform) with a short ER diagram and a table list that explains purpose and key columns.
  • Include DACPAC build/publish steps from db/sqlproj, seed scripts from db/sqlproj/seeds, and the admin DB health-check tool used for runtime SQL validation.

Reasoning Engine & Workflows​

  • Add an architecture diagram and minimal how-to-run (local command, example payload, expected result) plus a link to sample tests.

Admin & Debugging Tools​

  • Catalog admin tools (packages/platform-runtime/src/tools/admin) with example commands and expected outputs.

Templates & checklists​

  • Link to Authoring checklist and run the Docusaurus builds (npm --prefix docusaurus-docs run build:internal and npm --prefix docusaurus-docs run build:external) to catch broken MDX and navigation regressions.

Next steps​