Skip to content

PyCharter Architecture

Layered Architecture

PyCharter follows a four-layer architecture. Each layer depends only on layers below it — never on layers above.

Layer 0: Stateless Core (pure Python, no I/O)

The core business logic. No database imports, no HTTP, no file I/O.

  • pycharter.semantic.contracts.models — ContractConfig, field bindings
  • pycharter.semantic.contracts.runtime — coercion, annotation
  • pycharter.pipeline_artifact.models — CanonicalPipelineConfig
  • pycharter.semantic.concepts.models — Concept, Relationship (canonical, VC-5)
  • pycharter.semantic.concepts.graph.validator — validation rules
  • pycharter.semantic.concepts.graph.linkml_projection — projector
  • pycharter.semantic.knowledge_base.models — KBVersion, KBLink, LineageRecord
  • pycharter.pipeline_generator.steps._base — step config models
  • pycharter.pipeline_generator._dag — DAG resolution
  • pycharter.pipeline_generator.step_contract — runtime adapter

Layer 1: Persistence (DB, file I/O)

Repository classes that map domain models to storage.

  • pycharter.persistence.drafts.sqlalchemy_repository
  • pycharter.persistence.search.sqlalchemy_source
  • pycharter.persistence.versioning.history
  • pycharter.persistence.collaboration.review + proposals
  • pycharter.persistence.ingestion.importer
  • pycharter.semantic.concepts.graph.sqlalchemy_repository
  • pycharter.pipeline_generator._validation_rules (DLQ DB access)
  • pycharter.contract_store (5 backends)

NOTE: concept_graph.sqlalchemy_repository and pipeline_generator._validation_rules still live outside the persistence/ package. The concept graph repo follows the correct adapter pattern and is arguably fine where it is; the validation rules file needs a future refactor to extract its DB access into a provider.

Layer 2: API (FastAPI routes)

Thin HTTP handlers that compose the core and persistence layers.

  • pycharter.api.routes.v1.*
  • pycharter.api.models.* (Pydantic wire shapes)
  • pycharter.api.dependencies.*

Layer 3: UI (Next.js + React + Zustand)

  • pycharter.ui.src.stores.* — Zustand stores
  • pycharter.ui.src.components.* — React components
  • pycharter.ui.src.lib.api.* — API client wrappers