Skip to content

Architecture Overview

This section is the contributor map for the Dataface codebase.

Use it to answer three questions quickly:

  1. What are the main systems in this repo?
  2. Which parts are platform code versus application surfaces?
  3. Where should canonical documentation live?

Repo shape

At a high level, the repository has four different kinds of code:

Area Path Role
Core platform dataface/ Shared engine, CLI, AI integrations, and platform services
Applications apps/ User-facing product surfaces built around the platform
Internal libraries libs/ Semi-independent packages and tooling with their own local docs
Planning and notes master_plans/, ai_notes/ Execution tracking and working knowledge 
flowchart TD
    platform["dataface/\nplatform package"]
    apps["apps/\nproduct surfaces"]
    libs["libs/\ninternal packages"]
    docs["docs/\ncanonical contributor docs"]
    notes["ai_notes/\nworking notes"]
    plans["master_plans/\nplanning and execution"]

    apps -->|call into| platform
    docs -->|describe| platform
    docs -->|describe| apps
    notes -->|support| docs
    plans -->|track work on| platform
    plans -->|track work on| apps

Read in this order

Documentation rules

Keep documentation in the layer where it is most likely to stay accurate:

  • Put stable platform and application architecture in docs/docs/contributing/architecture/
  • Keep workflow and agent instructions in repo-level AGENTS.md and CLAUDE.md
  • Keep tool- or library-specific canonical docs close to the code in libs/*
  • Keep drafts, explorations, and temporary reasoning in ai_notes/
  • Keep milestone and task execution state in master_plans/

Libraries are different

The libs/ directory contains packages such as cbox, asql, and markdown-svg. These should generally keep their canonical docs next to the library itself rather than being duplicated in the central architecture section.

The central architecture docs should only explain:

  • what the library is for
  • how it relates to the Dataface platform
  • where its canonical local documentation lives