The Tom framework

A Dart/Flutter enterprise & AI ecosystem — explore every module and component, what it does, and how far along it is.

0
released
19
published
17
in the works
4
not started

Anatomy of a Tom application

A Tom application is a Flutter **client** and a Dart **server** joined by a typed interface, with the server reaching external services and an application-owned **MySQL/PostgreSQL** database. Both halves are built on **Tom Core** — `tom_core_flutter` and `tom_core_server` over a shared `tom_core_kernel` and `tom_basics` foundation.

Tom Core guarantees, by construction, what every enterprise app needs and every app should share: a resource-driven configurable UI, full internationalization, uniform authentication and a four-state authorization system, one architecture, and uniform deployment, operations and provisioning. These are enforced by the framework — independent of how the business logic was written.

Built by a specification flow

Business logic is produced through a staged flow — **manual specification → DocSpec → CodeSpec → implementation** — orchestrated by **ai_build**. ai_build scripts the steps on **tom_flow**, draws on **tom_brain** for the AI specification and coding work (through external interfaces), and both execute dynamic, sandboxed code through **D4rt**. **tom_reflection** provides the runtime reflection that lets an application assemble itself.

Agentic surfaces

The same architecture can host AI-generated agents: a server can expose **tom_brain** as a service that produces agentic apps which run inside the Flutter client via **tom_d4rt_flutter**.

Around the framework

Framework development and operations run in parallel — a VS Code extension and the **Tom Forge** IDE for authoring, command-line **DevOps** tools for build and deployment, and a **Cloud** layer for provisioning. Two companion applications, **tom_uam** (users & authorization) and **tom_sqm** (subscriptions & quota), ship on Tom Core.

Architecture at a glance

flowchart TB subgraph App["A Tom application"] C["Client · Flutter"] <--> I["Typed interface"] <--> S["Server · Dart"] S --> X["External services"] S --> DB[("MySQL / PostgreSQL")] end C --- CF["tom_core_flutter"] S --- CS["tom_core_server"] CF --- K["tom_core_kernel"] CS --- K K --- B["tom_basics"] subgraph Flow["Creation flow"] M["Manual spec"] --> D["DocSpec"] --> CO["CodeSpec"] --> Impl["Implementation"] end AB["ai_build"] --- Flow AB --> TF["tom_flow"] AB -. external .-> TB["tom_brain"] TF --> D4["D4rt"] TB --> D4 Impl -. generates .-> S

Areas

Start with an area — the big picture — then drill into its components and modules.

→

Dart Interpreter

1 member
Tom runs and generates code at runtime through a sandboxed Dart interpreter.
 →

Reflection

1 member
Applications assemble themselves at runtime, and tools read a codebase's API without re-running the analyzer.
→

Foundations

1 member
The shared floor every Tom package builds on.
 →

Code Generation

2 members
Much of Tom is generated.

Components

Each component is a family of modules — hover for its status mix, click to open its modules.

→

Basics

basics · 10 modules
12.8k loc · 935 tests · 13.0k test LOC
The foundation layer beneath the Tom stack: a minimal-dependency utility package plus a CLI/tooling framework, surrounded by focused extensions for console, network, crypto, chat, and code-generation support.
0 rel 7 pub 1 wip 2 ns
→

Core

core · 9 modules
495.3k loc · 2.5k tests · 251.7k test LOC
0 rel 0 pub 8 wip 1 ns
→

D4rt

d4rt · 13 modules
1.3M loc · 12.8k tests · 3.2M test LOC
D4rt runs Dart source at runtime in a permission-guarded sandbox. It is the dynamic-execution engine that lets Tom's AI scripting and flow layers generate and run code safely.
0 rel 9 pub 4 wip 0 ns
→

Reflection

reflection · 5 modules
28.4k loc · 410 tests · 285.3k test LOC
The reflection layer gives Tom programs runtime introspection and dynamic invocation, plus analyzer-based extraction of a codebase's API. It is the base technology behind auto-assembling Tom applications at runtime.
0 rel 2 pub 2 wip 1 ns
→

Vscode

vscode · 3 modules
96.8k loc · 1.5k tests · 19.3k test LOC
The VS Code extension ecosystem used to develop the Tom framework. A TypeScript extension hosts a Dart bridge that runs Dart scripts inside the editor with full VS Code API access, driven by a typed Dart scripting layer.
0 rel 1 pub 2 wip 0 ns