Platform Overview¶
This page describes how the main code areas fit together.
Main platform package¶
The dataface/ package is the shared platform layer. It contains the engine and the interfaces built directly on top of it.
| Area | Path | Purpose |
|---|---|---|
| Core engine | dataface/core/ |
Compile, execute, render, inspect, and serve dashboards |
| CLI | dataface/cli/ |
dft command surface for local and scripted use |
| AI | dataface/ai/ |
AI context contracts, MCP support, prompts, and tools |
These components form the reusable foundation for the application surfaces in apps/.
Applications¶
The apps/ directory contains product surfaces with their own UX, runtime model, and contributor concerns.
| App | Path | Role |
|---|---|---|
| Cloud | apps/cloud/ |
Django application for hosted dashboard authoring and management |
| Playground | apps/playground/ |
Fast, live-editing environment for dashboard iteration and demos |
| IDE | apps/ide/ |
VS Code / Cursor extension surface |
| Docs | apps/docs/ |
Documentation delivery/build surface |
| A Lie | apps/a_lie/ |
Separate AI-facing application surface |
See Applications for the app-by-app map.
Typical dependency direction¶
In general, the architecture should read like this:
apps/* -> dataface/core
apps/* -> dataface/cli or dataface/ai (when needed)
dataface/cli -> dataface/core
dataface/ai -> dataface/core and platform metadata
The important boundary is that the engine lives in dataface/core/, while app-specific workflow and UI behavior lives in apps/*.
Shared libraries¶
The libs/ directory contains related but semi-independent packages:
| Library | Path | Notes |
|---|---|---|
| ASQL | libs/asql/ |
Query-language and compiler package with its own docs |
| CBox | libs/cbox/ |
Sandbox/review workflow tooling with library-local instructions |
| markdown-svg | libs/markdown-svg/ |
SVG rendering utility package |
These are not the same thing as the apps/ surfaces. They should keep canonical detailed docs locally, with only light linking from central contributor docs.
Canonical doc placement¶
Use this rule of thumb:
- If the topic explains how the main Dataface platform works, document it here.
- If the topic explains a specific app surface, document it in this architecture section under applications.
- If the topic explains a semi-independent library or tool in
libs/, keep the detailed docs with that library.