Tom Core — the foundation layer of the Tom Framework

> Attribution. The Tom Framework is developed by Peter Nicolai Alexis Kyaw. > These packages are proprietary and internal (publish_to: none).

Tom Core is the set of packages every Tom application is built on: a platform-neutral kernel (dependency injection, observable state, security, resources, logging) and the runtimes layered on top of it — a server stack, two Flutter layers, a DartScript bridge tool, a VS Code bridge server, and a set of agentic building blocks.

This repository (al-the-bear/tom_core) holds the whole layer. This document is the map; each package has its own README.md and doc/ folder for the detail. Nothing about a package's API is re-documented here — one phrase of "what it is" plus the link is the contract.

> New here? The richest on-ramp is the upcoming tom_core_samples/ learning > path (see Sample learning path). Until it lands, read > tom_core_kernel (the foundation) and run one of > the two live demo apps — tom_flutter_form_test > (the form stack) or tom_flutter_ui_test > (the full widget set).

---

What you can do with Tom Core

• Build a backend service — HTTP host, an endpoint pipeline, a type-safe

relational persistence layer with datasources and migrations, configuration, caching, and authentication/authorization — from one dependency (tom_core_server). - Build a Flutter app from authorization-aware, observable, resource-bound widgets — a Material/Cupertino widget set, a declarative form system, and a fluent layout engine (tom_flutter_ui). - Share one model of state, security, and resources across server and client — the platform-neutral tom_core_kernel is the single source of those cross-cutting concerns. - Script the framework — expose the kernel, server, build, and document toolkits to sandboxed DartScript through tom_core_d4rt. - Assemble agent runtimes from generic, domain-free, dart:io-free building blocks (tom_core_agentic).

---

How the layer fits together

Everything roots at the kernel. The two runtimes (server and Flutter) re-export it, so an app depends on one of them and gets the kernel API for free. The UI library is the rich widget set that the Flutter runtime's thin integration layer complements. The scripting and bridge tools wrap the runtimes for DartScript and the VS Code extension. The agentic blocks sit beside the kernel, depending only on tom_basics.

                    tom_core_kernel            (platform-neutral foundation)
                   /       |        \
       tom_core_server  tom_core_flutter  tom_flutter_ui
         (backend)      (Flutter glue)    (widget library)
              |
       tom_core_d4rt  ── tom_core_bridge        (DartScript / VS Code bridge)

       tom_core_agentic  (agent building blocks; depends only on tom_basics)

---

The packages

Every package below has a README.md (linked) and a doc/ folder. Base path for all entries is this repository root.

Foundation

Package	What it is
tom_core_kernel	The platform-neutral foundation: dependency injection (bean locator), observable state, security and four-state authorization, resource resolution, logging, JSON, and runtime utilities. Reflection-aware; no UI or server-runtime dependency, so any Dart target can consume it.

Runtimes

Package	What it is
tom_core_server	The server layer: an HTTP host, an endpoint pipeline, a relational persistence layer with a type-safe query model, datasources and migrations, server configuration, caching, and authentication/authorization. Re-exports the kernel through its own barrel.
tom_core_flutter	The Flutter integration layer: re-exports the kernel and adds Flutter widgets that bind to observable kernel state, form primitives, typed UI properties, client-side platform detection, and client auth helpers.

UI

Package	What it is
tom_flutter_ui	The Flutter widget library: a Material/Cupertino-aware widget set, a declarative form system, a behavioural action system, and a fluent row-based layout engine (Advanced Container Layout). Every widget understands the kernel's tomId / tomGroup visibility, the four-state TomAuthState model, and resource-driven styling.

Scripting & bridges

Package	What it is	Binary
tom_core_d4rt	The D4rt scripting tool with the full Tom Framework bridge set — an interactive REPL and headless script runner that exposes the kernel, server, build, distributed, and document toolkits to sandboxed DartScript.	d4rt
tom_core_bridge	The VS Code bridge server extended with the complete Tom D4rt bridge set — tom_bs (DCli + VS Code API bridges) plus everything tom_core_d4rt registers.	core_bs

Agentic

Package	What it is
tom_core_agentic	Generic, domain-free, dart:io -free building blocks for agentic systems — placeholder resolution, path-scoped sandboxing, content-hash conventions, config read/write. Depends only on tom_basics ; reusable across the brain, the assistant, and any agent runtime.

Demo & test apps

These are runnable harnesses (publish_to: none), not libraries — they exercise the layer end-to-end against the live Flutter engine.

App	What it is
tom_flutter_form_test	A two-tab Flutter showcase of the form framework ( tom_flutter_ui forms/fields over the kernel's resources, security, and reflection). See its demo catalogue .
tom_flutter_ui_test	A four-tab Flutter demo / smoke-test of the whole tom_flutter_ui library — the ACL layout engine, the widget set, the form framework, and the resource/authorization machinery. See its demo catalogue .

---

Sample learning path

A dedicated tom_core_samples/ folder is forthcoming (Tom Core quest, README & samples plan, Phase B). It will build one todo-management application across six subprojects, ordered as a learning path from a backend up through responsive UI. Until those land, the two demo apps above are the live, runnable reference.

Order	Sample (planned, tom_core_samples/…)	Introduces
1	core_server_sample	The server stack against MySQL-in-Docker — endpoints, persistence, auth, healthcheck.
2	core_client_sample	A Flutter todo app on tom_core_flutter + tom_flutter_ui , talking to the server, with ACL-driven field states.
3	core_flutter_ui_showcase	Every tom_flutter_ui widget group, each shown with 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 Advanced Container Layout engine — sizing, growth, alignment, nesting, borders, variants, and the four authorization states.
6	core_flutter_acl_responsive	Responsive UIs on the ACL engine — breakpoints, family-swap, adaptive layouts across phone/tablet/desktop.

---

Documentation index

Each package keeps its user documentation in its own doc/ folder; the READMEs above link the relevant files. The most common entry points:

Topic	Document
Kernel module reference	tom_core_kernel/doc/ (per-module folders)
Server modules (persistence, endpoints, auth, …)	tom_core_server/doc/
Flutter integration modules	tom_core_flutter/doc/
Widget library — ACL engine	tom_flutter_ui/doc/advanced_container_layout.md
Widget library — forms & authorizers	tom_flutter_ui/doc/forms.md · form_authorizers.md
DartScript bridge groups	tom_core_d4rt/doc/ (one .md per bridged package)
VS Code bridge operations	tom_core_bridge/doc/operations.md
Agentic building blocks	tom_core_agentic/doc/
Form demo catalogue	tom_flutter_form_test/doc/demo_catalogue.md
UI demo catalogue	tom_flutter_ui_test/doc/demo_catalogue.md

---

Repository layout

tom_core_kernel/       platform-neutral foundation (DI, state, security, …)   (foundation)
tom_core_server/       backend runtime: HTTP, persistence, auth               (runtime)
tom_core_flutter/      Flutter integration layer (re-exports the kernel)      (runtime)
tom_flutter_ui/        Flutter widget library: widgets, forms, ACL engine     (UI)
tom_core_d4rt/         DartScript REPL + runner with full Tom bridges (d4rt)   (scripting)
tom_core_bridge/       VS Code bridge server with the Tom bridge set (core_bs) (bridge)
tom_core_agentic/      domain-free agentic building blocks (dart:io-free)      (agentic)
tom_flutter_form_test/ runnable demo: the form framework                      (demo app)
tom_flutter_ui_test/   runnable demo/smoke-test: the whole widget library     (demo app)

Dependency direction, simplified: everything roots at tom_core_kernel; tom_core_server and tom_core_flutter build on and re-export it; tom_flutter_ui builds on the kernel and is exercised by the two demo apps; tom_core_d4rt bridges the runtimes into DartScript and tom_core_bridge serves those bridges to the VS Code extension; tom_core_agentic depends only on tom_basics.

License

Proprietary and confidential. Each package carries the same proprietary LICENSE; see any package folder for the full text.