The Core Application Framework is the foundation every Tom application is built on: a Flutter client and a Dart server joined by a typed interface, both resting on a shared kernel. It is one of the seven building blocks of the framework, and the one that defines what a "Tom application" is.

Its defining promise is uniformity by construction. Tom Core guarantees — for every app, regardless of how that app's business logic was written or generated — a resource-driven configurable UI, full and uniform internationalization, uniform authentication, a uniform four-state, per-resource authorization system, one architecture, and uniform deployment, operations, and provisioning. These cross- cutting features live in Core, so they are present in every Tom app automatically; the application creation flow only generates business logic on top of them.

The shape of a Tom application

        client app (Flutter)            server app (Dart / Shelf)
                │                                  │
     tom_core_flutter + tom_flutter_ui       tom_core_server
                └──────────────┬──────────────────┘
                        tom_core_kernel
                          tom_basics

• The client is a Flutter app built on tom_core_flutter and the

tom_flutter_ui widget library. - The server is a Dart/Shelf server built on tom_core_server, reaching external services and an application-owned relational (MySQL/MariaDB) database over a pluggable datasource layer. - A typed interface is the client⇄server contract between them. - Both halves rest on a shared tom_core_kernel and the tom_basics utility floor. The two runtimes re-export the kernel, so an app depends on one of them and gets the kernel API for free.

The components and modules

The area is delivered by the Core component (core) and its modules.

The layered base

• tom_core_kernel — the platform-neutral foundation every other layer is

composed from: dependency injection (bean locator), observable state, security and the four-state authorization model, resource resolution, logging, JSON, isolate pooling, settings, runtime utilities, and the reflection glue that turns generated reflection data into runtime wiring. No UI and no server runtime, so it runs unchanged on CLI, server, and Flutter targets. - tom_core_server — the server stack from one dependency: an HTTP host, an endpoint pipeline, a relational persistence layer with a type-safe query model, datasources and migrations, server configuration, caching, transactions, health checks, and authentication/authorization. - tom_core_flutter — the thin binding layer that brings the kernel onto a Flutter target: it re-exports the kernel and tom_reflection, and adds widgets that bind to observable kernel state, form primitives, typed UI properties, client-side platform detection, and client auth helpers.

The UI library

• tom_flutter_ui — the Flutter widget library: a Material/Cupertino-aware

widget set, a declarative form system with authorizers, the Tom Action system, theming, and the fluent row-based Advanced Container Layout (ACL) engine. Every widget understands the kernel's tomId/tomGroup visibility, the four-state authorization model, and resource-driven styling, so a UI is configured from resources rather than hard-coded. - tom_flutter_form_test / tom_flutter_ui_test — two runnable Flutter showcases (two tabs for the form framework, four tabs for the whole widget library) that exercise the layer end-to-end against the live Flutter engine and remain the broadest live reference for the UI layer. Each ships a demo catalogue.

Agentic and CodeSpecs glue

• tom_core_agentic — generic, domain-free building blocks for agentic

systems: placeholder resolution, path-scoped sandboxing, content-hash conventions, cooperative cancellation, category logging, shutdown coordination, and typed YAML config read/write. It depends only on tom_basics, and 31 of its 36 exports are dart:io-free — the subset that lets dart:io-forbidding packages such as tom_brain_shared build on it, which is why Tom Brain shares it. - tom_core_codespecs — the CodeSpecs gap classes for the tom_core family. TomSpecs Phase 4 generates a skeletal application in which every instantiated class must come from tom_core_kernel, tom_core_flutter, tom_core_server, or tom_flutter_ui; for the handful of parts where the framework has the runtime half but not the authoring half, this package supplies the concrete classes — kept outside tom_core so it stays free of concerns only a generator has. It is the one member of the TomSpecs release-1 chain that lives in the Core tree.

Samples and learning path

Core is taught through code, not only prose. tom_core_samples builds a single todo-management application across a shared domain and six subprojects, ordered as a learning path from the backend up to responsive UI:

0. todo_domain — the shared reflected entities (User, Project, TodoList, TodoItem) every other sample reuses. 1. core_server_sample — the server stack against MySQL-in-Docker: endpoints, persistence, auth, healthcheck. 2. core_client_sample — a Flutter todo app with four-state field authorization; in-memory backend by default, live read path to the server. 3. core_flutter_ui_showcase — every tom_flutter_ui widget group, each shown beside its instantiation code. 4. core_flutter_form_showcase — the forms framework in depth: field types, validation, layout, theming, master-detail, lists. 5. core_flutter_acl_sample — the ACL engine: sizing, growth, alignment, nesting, borders, variants, and the four authorization states. 6. core_flutter_acl_responsive — responsive UIs on the ACL engine across phone, tablet, and desktop.

The Advanced Tom Core Full-Stack Sample is the secured successor to the basic server/client pair: eight packages forming three servers (a JWT auth/admin server, a secured task-manager app server, a back-office operations server), two databases, and two Flutter clients (an end-user app and an administrator console), sharing one reflected domain and one wire contract with live four-state field authorization and cross-user sharing. Its map doubles as the long-form Tom Core user guide, which walks the architecture and the implementation rules the framework imposes.

Samples are publish_to: none and carry no API mirror by design — each ships an article-grade README instead, and the two demo apps above stay the broadest runnable reference.

How it fits the rest of Tom

Core is the destination of the application creation flow and the host of the agentic line. The Software Factory produces business logic that targets Core's contracts: TomSpecs Phase 4 derives the CodeSpecs skeleton against the four tom_core-family packages (plus tom_core_codespecs), and the implementation phase fills it in. Reflection (tom_reflection, via the kernel's reflection glue) is what lets an application assemble itself from resources at runtime. And in the agentic variant, the server can expose tom_brain as an external service whose generated agent surfaces run inside the Core-based Flutter client through tom_d4rt_flutter.

The two companion applications — tom_uam (users & authorization) and tom_sqm (subscriptions & quota) — are themselves built on Core, serving double duty as production apps and as canonical samples of how to build on the framework; tom_uam is the application-sized consumer the repository's gates keep on Core's current level.

> Maturity note. Tom Core is complete: the packages are documented and tested > (every package suite plus a repository-wide documentation gate suite that holds > the prose to the code run before a change is called finished), the samples and > the full-stack sample are built, analyze-clean and green, and the four-state authorization model runs through the security code > end to end. The packages are BSD-3-Clause licensed and internal > (publish_to: none): consume them from the tom_core repository by path, not > from pub.dev, and expect no backwards-compatibility guarantee until the layer is > published.