Architecture
ContractSpec's architecture is built on a foundation of typed specifications served by runtime adapters. This section covers the core architectural concepts: app configuration, integration binding, and knowledge management.
Core layers
1. Specification Layer
The foundation of ContractSpec. Typed specifications define what your application can do:
- CapabilitySpec - Operations and their inputs/outputs
- DataViewSpec - Data queries and presentation
- WorkflowSpec - Multi-step processes
- PolicySpec - Access control and data protection
- IntegrationSpec - External service providers
- KnowledgeSpaceSpec - Knowledge and context management
2. Configuration Layer
How applications are configured and customized:
- AppBlueprintSpec - Global, versioned app definition
- TenantAppConfig - Per-tenant, per-environment configuration
- AppIntegrationBinding - How apps use integrations
- AppKnowledgeBinding - How apps access knowledge
3. Runtime Layer
How specifications are executed at runtime:
- ResolvedAppConfig - Merged blueprint + tenant config
- Policy Decision Point (PDP) - Enforces policies on every operation
- Presentation Runtime - React and React Native renderers
- Integration Connectors - Execute external API calls
- Knowledge Retrieval - Query vector databases and knowledge sources
Configuration model
ContractSpec uses a three-tier configuration model:
| Layer | Type | Scope | Storage |
|---|---|---|---|
| Blueprint | AppBlueprintSpec | Global, versioned, no tenant info | Version control, immutable |
| Tenant Config | TenantAppConfig | Per-tenant, per-environment | Database, mutable |
| Resolved Config | ResolvedAppConfig | Runtime, ephemeral | In-memory, not persisted |
Key architectural principles
- Spec-first - Everything is defined declaratively before code generation
- Type-safe - All specifications are strongly typed and validated at compile time
- Policy-enforced - Every operation passes through the PDP
- Multi-tenant by default - Tenant isolation is built-in, not bolted on
- Environment-aware - Separate configurations for sandbox, staging, production
- Auditable - All operations are logged for compliance and debugging