Skip to content

Architecture Foundations

The foundations docs define the stable contracts that app authors and runtime contributors should share before reading implementation deep dives.

Reading Path

  1. Distribution And Workspace Model
  2. Framework Capability Classification
  3. Canonical App Structure
  4. App Manifest and Platform Targets
  5. App Bundle Declaratives
  6. Core, Product, and App Bundle Boundary
  7. Account, Admin, and Platform Services
  8. Workflow Architecture
  9. Workflow Authoring Contracts
  10. Declarative AG2 Mapping
  11. Event System
  12. Event Contracts

Contract Summary

  • Mozaiks framework code lives in mozaiksai/, chat-ui/, the repo-local web shell host, CLI, and the shared generation core.
  • Not all first-class framework code is universal app-runtime substrate: the runtime, platform host, and core shell primitives are universal, while Studio, CLI, and shared generation core are optional framework-owned capabilities.
  • factory_app/app is the first-party Studio app bundle in this repo, and generated/hosted app workspaces follow the same self-contained contract with app/config, app/ui/pages, app/workflows, app/modules, app/ui, and app/brand.
  • Deterministic app behavior is hosted by mozaiksai/hosts/platform.py modules or by an optional external/generated backend connected through AppBackendPort.
  • Profile, settings, notifications, subscriptions, and admin are first-class deterministic platform services, not workflow-owned product surfaces.
  • Workflows are declarative AI runs owned either by an app workspace or by the shared generation core.
  • App UI pages are declarative page surfaces owned by the app workspace.
  • Deterministic app behavior belongs behind explicit runtime/backend contracts, not inside workflow prompts.
  • App events and workflow triggers connect ordinary app behavior to AI runs.

For the full repository-level architecture, see ARCHITECTURE.md.