A map of what each guide covers, organized by category. If you’re not sure which guide to read, start here.
WhyFOAM Answers why FOAM succeeds where earlier model-driven systems failed. Covers twelve principles: never editing generated code, fine-grained Lego-like components, context-based composition, RISC-y APIs, active runtime models, self-modelling, and feature-orientation. Read this first if you want to understand the philosophy before the mechanics.
Concepts Introduces the key pillars of FOAM thinking: meta-programming, Model-Driven Development, Feature-Orientation (Unix-like composability), and meta-circularity (the model models itself). A short conceptual orientation before diving into code.
Intro Developer introduction: what FOAM is (a cross-platform MDD framework for JS/Java/Swift), its core philosophy (declare models, generate everything), and a tour of the key features — reactive binding, built-in UI, DAOs, and cross-platform output.
Build The FOAM Pom-O-Matic build system: POM file types (Tooling vs Build), the three build phases (Tooling, Environment/Registration, Task), and the command-line flag styles the Node-based build tool supports.
POM Reference for POM (Project Object Model) file attributes: name/vendorId/version/licenses, multi-stage JS loading for startup performance, flags expressions for conditional inclusion (js/java/web/node/debug), JSLibs, and how the build processes sub-projects.
Context Explains the immutable hierarchical key-value Context (X) — its get/put/putFactory API — and the three-level hierarchy: system context (boot), session context (per-user), and request context (per HTTP request). Read this before learning about imports and exports.
DesignPatterns Catalogs the design patterns FOAM uses throughout: Strategy, Proxy, Decorator, Bridge, Observer, Composite, Interpreter, Command, Factory, NullObject, Flyweight, Facade, Builder and Prototype. Useful for understanding why the framework is structured the way it is.
models
Reference for FOAM model types: foam.CLASS (data models), foam.ENUM (fixed value sets), foam.INTERFACE (contracts), foam.SCRIPT (code run once at load time), foam.RELATIONSHIP (model connections), and foam.LIB (namespace extensions).
Axioms
Explains Axioms as the core extension mechanism — the pseudo-interface with installInClass/installInProto that all higher-level constructs (Properties, Methods, Listeners, Actions, Topics, etc.) implement. Covers two-phase installation and priority ordering.
Enum
Covers FOAM Enums: declaring them with foam.ENUM, defining values with ordinal/label/properties/methods, built-in ordinal and name properties, and usage patterns analogous to Java enums.
FSM
Covers FOAM state machines: foam.FSM, the StateMachine property and the history, payload and next-activity properties it adds, guards, permissions, Java lifecycle hooks, scheduled activities, and server-side enforcement with FSMDAO.
Refinements Explains Refinements as the mechanism to extend or modify existing FOAM classes post-definition without creating a subclass. Covers the two-phase installation, common patterns (adding properties, view defaults, Java code generation), and how refinements bootstrap FOAM’s self-modelling.
MixinsAndImplements
Compares implements: (interface-like semantics with safe override handling via an intermediate axiomMap level) vs mixins: (direct unconditional axiom copy with no conflict resolution). Use implements: unless you explicitly want overwrite behaviour.
Relationships
Covers FOAM Relationships (one-to-many and many-to-many): how they differ from Reference properties, foam.RELATIONSHIP declaration syntax, what gets generated (FK properties, filtered DAOs, junction models), and UI integration via DAOBrowserView.
Listeners
Covers Listeners as pre-bound methods that retain this in callbacks, declaring them in short or long form, timing options (isMerged/isFramed/isIdled), the built-in pub/sub topic system, and declarative on: subscription binding.
Actions Covers Actions as methods with GUI metadata (label, availability, enablement, icon, confirmation, shortcut) that views render automatically as buttons. Contrasts Actions with plain methods and Listeners, and explains why they replace hand-wired button+onClick+guard combinations.
REQUIRES_VS_IMPORTS
Explains the difference between requires: (class dependencies — makes a short name available as a factory method with automatic context passing) and imports: (runtime DI — pulls live service instances from context). A short but essential read before any serious view or service work.
Dao Comprehensive DAO guide: how to make a class storable, the full JS and Java DAO interfaces (put/find/remove/select/listen/removeAll/where/orderBy/limit/skip/inX), filtering, the common sinks, EasyDAO overview, and MLang predicates. The primary DAO reference.
EasyDao Explains EasyDAO as a one-stop DAO configurator: storage type (IDB/LOCAL/MDAO), caching, ID assignment (seqNo/guid), synchronization, journaling, and authorization flags. Read this when setting up a new DAO.
DaoExamples Hands-on code examples for ArrayDAO, put, find, select with predicates and sinks — can be run in a Chrome console or Node REPL. Good for experimenting with the DAO API.
DaoGotchas
Catalog of non-obvious DAO behaviors: which context a decorator predicate filters against, why argless find/select re-enter with the DAO’s own context, how arity-1 select drops query arguments, frozen-object semantics, decorator stacking order, CachingDAO TTL branch, LimitedSink under GROUP_BY, and LTE matching unset dates. Read this when something in a DAO chain behaves unexpectedly.
Sink Reference for FOAM Sinks: the four-method interface (put/remove/eof/reset), the source-to-sink streaming architecture, all common built-in sinks (ArraySink/COUNT/SUM/MAX/MIN/GROUP_BY/MAP/UNIQUE), and sink delegation and chaining.
Journals
Explains FOAM journals: append-only .jrl files using p/c/r/v operations with JSON delta compression, their roles in persistence, build integration, and deployment, the directory hierarchy, replay at startup, and how compaction reduces replay time.
MultiPartKeys
Explains composite primary keys in FOAM via the ids array, automatic generation of a typed ID class with create/parse/compare methods, and how to find objects by multi-part key.
Updating Objects in DAOs
Explains the read-copy-edit-put pattern for updating DAO objects: why returned objects are frozen, using clone()/fclone() before mutation, and how the DAO stack (validation, auth, journal) processes the put.
Compaction Covers FOAM journal compaction: the five-step process (block, roll/backup, unblock, compact, complete) that rewrites many delta entries into one entry per object to speed replay. Includes configuration, custom sinks, rollback procedure, and gotchas.
NDiff
Covers NDiff, a debugging and change-tracking tool for CSpecs that captures initial journal state, compares it to runtime state, and enables visual before/after comparison and restore. Configured via setNdiff(true) on EasyDAO.
DaoEventsAndRefresh
Explains the three DAO events (put/remove/reset), how they bubble up through the decorator chain to views, how to subscribe with listen/on.put.sub, and when to force a manual refresh.
ApplicationController
Documents foam.core.controller.ApplicationController, the top-level client shell: navigation stack, authentication lifecycle, theming, notifications, and session management. Covers the ~30 named context exports (pushMenu, notify, subject, theme, displayWidth, etc.), the lifecycle flow, and ZAC as the intended micro-service successor.
Comics
Explains foam.comics.v3 (Context-Oriented MIcro ControllerS): how the DAOController state machine composes three micro-controllers (DAOView, CreateView, DetailView) to generate a full CRUD UI — table, search, detail form, create form, sorting, export — automatically from one model declaration. Covers DAOControllerConfig knobs, CRUD predicates, ComicsAction overrides, and canned queries.
Memento
Explains foam.u2.memento.Memento, FOAM’s hierarchical URL-hash state sync (memorable: true properties, the parent/tail Memento chain, and the special-cased route property that becomes a path segment instead of a key=value param), WindowHashMemento’s browser-hash binding, and the foam.u2.Router mixin built on top for route-driven view switching. Includes a gotchas section (stale tail bindings, a duplicate Router class definition).
U3
Documents U3 (foam.u2), FOAM’s wrapped-DOM reactive GUI library: history (U1 templates → U2 virtual DOM → U3 direct DOM), the Node class hierarchy (Text/SlotNode/FunctionNode/Element), DOM building via start/end/add/tag, add() polymorphism, CSS scoping with ^, reactive slots, ControllerMode/DisplayMode/visibility pipeline, onDetach cleanup, and the render() method contract.
CSSTokens
How to think about CSS tokens: where a $token’s value comes from (class, shared list, theme row), a value is the fallback and a mode entry wins, the color and density axes in activeVariants, what useVariants gates, which class to declare (a colour is a ColorToken; a non-colour that flips with mode is CSSToken + variantKey; the rest plain), how to add a token and the spacing/radius/shadow/z-index/motion scales, and theme override rows.
ReactiveUI
Explains FOAM’s four reactive UI patterns from lightest to heaviest: slot binding (prop$), slot.dot() for nested properties, slot.map() for value transforms, and dynamic() for DOM-structure rebuilds. Includes a decision framework for choosing the right pattern.
ReactivePatterns
Complete reference for all FOAM3 slot and reactive binding forms: PropertySlot (obj.name$), slot() lookup, deep $ chain via dot(), ExpressionSlot, dynamic(), linkFrom/linkTo two-way binding, and when to use each.
Slots
Conceptual and advanced reference for Slots as observable pointers: the C-pointer analogy, PropertySlot vs SubSlot vs ExpressionSlot types, the $ accessor, deep chains, two-way linking, and why slots are the backbone of FOAM reactive UI.
dynamic
Explains the difference between model-level property expression: (lazy, pull-based, reactive computed values) and this.dynamic() (eager, push-based reactive DOM content), covering when each fires and their key behavioral differences.
ControllerModeAndVisibility Documents the three-layer pipeline — ControllerMode (CREATE/VIEW/EDIT), per-property Visibility declarations (RW/RO/DISABLED/HIDDEN), and DisplayMode — that controls whether a property’s view is editable, read-only, disabled, or hidden.
Modals
Describes the modal component hierarchy: Popup (base, full-screen overlay), StyledModal (title/description/action bar), ConfirmationModal (primary/secondary actions), and ApplicationPopup (wizard flows with progress bar and branding). Includes usage guidance for each.
CSSLayout
What a css: block goes through before the browser sees it (installed on first create, the ^ and $token text rewrites), which box scrolls and how to pin a header, hiding with shown, and how popups, modals and the z-index layers stack.
Themes
How an app gets its look: which Theme a user gets (domain, then spid), cssTokens and ColorToken with their $hover/$foreground forms and dark variants, recolouring a theme with CSSTokenOverride rows, reading a token from JS, and the legacy %PRIMARY1% macros to avoid.
Notifications
Overview of the notification system: creating Notification objects via notificationDAO, extending the base class for custom types, display via the bell icon and NotificationCitationView, and how to write custom citation views.
QA2
The foam.QA2 decision-matrix questionnaire engine: AQL predicates, “answered” meaning a stored value, how the next question is chosen, custom question views, and the shape of the generated class.
Cells A conceptual essay exploring how spreadsheet cells unify input, display, computation, and storage to eliminate glue code, and arguing that FOAM extends this idea beyond the grid via FObjects and reactive expressions.
VsReact Compares FOAM (model-driven, cross-platform, built-in DAO layer, context DI) vs React (component-based UI library, virtual DOM, hooks, JS-only) across philosophy, architecture, dependency management, and UI component design.
VsWebComponents Compares FOAM and Web Components/Polymer (common Google origins, conceptual kinship). Explains that Web Components solve only the UI component problem while FOAM provides a single model declaration as the source of truth for UI, persistence, networking, validation, and cross-platform code generation.
LLM Argues that LLM-generated code repeats the code-generator liability trap at larger scale, and explains how FOAM’s declaration-over-code approach avoids this by generating behaviour at runtime rather than shipping generated implementation code that accumulates as a maintenance burden.
agentsnotprotocols Drawing on Bill Joy’s 2000 essay, argues that shipping executable agents rather than wire-protocol specifications eliminates interoperability problems. Explains how FOAM/CORE realises this: the CSpec registry delivers client agents on demand instead of requiring REST API negotiation.
Reflow
Overview of Reflow, FOAM’s Jupyter-style interactive console: the Console controller, Flow documents, Block execution units, the command system (dao/upload/save/load/flows), reactive properties via reactions_, data visualisation via DAO agents and Chart.js, and hierarchical scope management.
ExportingFlows
Step-by-step instructions for exporting a Reflow flow from the running app: open the flow DAO in Console, filter by name, open the Download link (JSON or journal format), copy it, and replace the entry in the .jrl source file.
Dashboard
Quick-start guide for building FOAM3 dashboards: creating a DashboardView with widget menus in menu.jrl, configuring CardWrapper/DAOTable/count widgets, and optional CitationViews.
claude A comprehensive LLM-oriented FOAM3 reference covering all major concepts: class definition, properties, methods, listeners, actions, context, DAOs, MLang, inheritance, pub/sub, relationships, enums, interfaces, POM, U2/U3, multi-tenancy/SPID, grammars, authentication, schema migration, and code-generation conventions. Intended as a context document for LLM-assisted development.
NanoServices
Comprehensive guide to FOAM’s nano-service architecture: location-agnostic service access via context DI, the Box messaging layer (Box/Envelope/RPCMessage), Stub/Skeleton RPC generation, CSpec registration, and a complete NotificationService example.
Services
Step-by-step guide to creating FOAM nano-services: define a foam.INTERFACE with skeleton: true, implement the server side, register via CSpec in services.jrl, optionally create a client stub. Explains how Stub→Network→Skeleton is transparent to callers.
Auth
Covers the FOAM authorization system: User/Group/Permission/Capability models, GroupPermissionJunction, pseudo-permission @-inheritance, and the SPID-based multi-tenancy model with hierarchical per-SPID permissions and the authorization flow.
Security Covers FOAM security at two levels: structural immunity (XSS impossible via U2/U3’s DOM-only builder API; SQL injection impossible via MLang’s typed predicate objects) and application security (CSpec-based service authorization). Short but important read.
Permissions Documents the permission system architecture: the check flow (User → Group → GroupPermissionJunction → Permission), permission string patterns, the AuthService decorator chain (PM → Caching → Capability → EnabledCheck → PasswordExpiry → TwoFactor → UserAndGroup), and CSpec authorization.
SPID
Comprehensive guide to the SPID multi-tenancy system: making models SPID-aware via ServiceProviderAware, how ServiceProviderAwareDAO transparently filters put/find/select/remove, hierarchical dot-separated SPIDs (e.g. acme.canada.eastcoast), and the Theme white-labelling model with per-SPID class registrations.
Deployment Covers FOAM deployment: building a tarball, uploading and installing remotely via SSH, common install flags (user, backup), JVM memory defaults and overrides, and other JVM tuning.
email-setup
Step-by-step guide for configuring email in a FOAM app: creating EmailServiceConfig (SMTP), EmailTemplate, and EmailConfig journal entries, then sending EmailMessage objects through notificationDAO.
EmailSystemArchitecture
Architecture overview of FOAM3’s email pipeline: the three config entry types (EmailServiceConfig/EmailTemplate/EmailConfig), the rule-driven processing flow, the template variable system, Microsoft Graph integration, and gotchas.
Safari
Short guide to running FOAM in Safari, which requires building with HTTPS (-J../foam3/deployment/https -a) and accessing https://localhost:8443, plus certificate trust steps in Keychain.
MLang
Reference with Java and JavaScript examples for MLang predicates (EQ/GT/AND/OR/IN/CONTAINS), aggregation sinks (COUNT/SUM/GROUP_BY), and ordering — covering both the static import style (Java) and ExpressionsSingleton/mixin style (JS).
DSL
Argues that FOAM’s power comes from layered DSLs that collaborate: foam.CLASS as an internal DSL, parser combinators for grammars, AQL as an external query DSL, and MLang as an internal predicate DSL — each layer able to introspect the one below.
foam_parsers_doc
Comprehensive reference for FOAM’s grammar-based parser library: all simple parsers (literal, range, chars, notChars), combinators (seq, alt, repeat, optional, until, str), Grammar creation with sym, semantic actions, auto-complete suggestions with sug(), and SmartView integration.
foam_parser_callback_system_explained
Deep-dive on FOAM’s parser callback system: the apply intercept mechanism on StringPStream, the two callback types (apply for low-level interception vs. semantic actions for symbol-level transformation), error detection, and grammar.getLastError().
AutoQueryParser Syntax reference for AQL (Automatic Query Language): AND/OR/NOT/grouping operators and value types (strings, numbers, booleans, dates, enums, StringArrays). Designed to work with the SmartView autocomplete component.
RISCyAPIs Applies the CISC vs RISC CPU analogy to framework API design. Because FOAM generates most of its own API calls rather than humans writing them, its APIs can be small, regular, and optimized for programmatic generation (like RISC) rather than for human ergonomics.
StyleGuide
FOAM coding style guidelines: Google JS Style Guide with FOAM exceptions (spaces inside parens, space after !, single-line braces under 80 chars, two-space indentation), naming conventions (CamelCase models, camelCase properties, UPPER_SNAKE constants), and the preference for modelling over prototyping.
cheat-sheet A long-form FOAM3 cheat sheet covering model/class definition syntax, property types and defaults, expression/dynamic behaviors, methods, listeners, actions, DAOs, reactivity patterns, and context/import/export patterns. Good to have open while writing FOAM code.
PropertyGotchas
Catalog of non-obvious property behaviors: when postSet doesn’t fire (value default, equal slot binding, deserialization ordering), why an expression goes cold (lazy one-shot subscription), javaFactory frozen-safety mechanics, javaGetter values not reaching the client via the isSet gate, and what transient cascades into. Read this when a property change seems to be silently ignored.
Tools One-page list of the developer tools that come with foam3: the language server, agent skills, live reload, debugging, tests and the build, each with the command that starts it and a link to its full guide.
LiveReload
Explains ./build.sh -l: save a .js file and the open page rewrites the stylesheet or rebuilds the on-screen instances in place, no page reload. Covers the console line, what a rebuild keeps and drops, the cases that still need a reload (boot classes, foam.SCRIPT, SlotNode-rendered views, the controller or popup class itself, refinement-only files), the server-side stat poll and its CPU cost, and how to tune skipDirs and the poll intervals.
Debugging
Practical debugging guide for both JavaScript (Chrome DevTools: breakpoints, postSet debugger trick, console commands, network tab) and Java (JDPA remote debugging in VS Code and IntelliJ, source file locations).
DebuggingCountAndUsed
Explains two FOAM debugging tools: cls.count_ (tracks instance creation count per class, incremented in create()) and foam.USED (registry of all classes actually instantiated in the current session, moved from foam.UNUSED on first lookup).
LSP
Setup instructions for the FOAM Language Server and its MCP server: the one-line installer per editor (VS Code, Emacs, Zed) and per coding agent (Claude Code, Codex, Gemini CLI, Cursor, Pi), the 10-15 second first boot, team defaults in foam-lsp.json, and what to check when the server stays quiet.
Testing
Covers the FOAM test harness: running all/server/client tests from the build, running specific test IDs or suites, excluding tests with -, the per-test SUCCESS/FAILURE output format, and modelling test cases as FOAM classes or scripts targeting Java or JavaScript.
APITesting
Covers FOAM’s built-in API testing support via the DIG (Data Interchange Gateway) client, which lets tests act as external users with scoped sessions while retaining full server-side DAO access. Extends foam.core.test.AbstractDIGTest.
Porting
Migration guide from FOAM1 to FOAM2/FOAM3: key API renames (CLASS → foam.CLASS, lazyFactory → factory, defaultValueFn → expression, traits → implements, addListener → sub) and behavioral differences (Promise-based DAO, CSS axiom, U2/U3 only, no built-in prototype extension).
DateTimeUTC
Documents the DateTimeUTC property type: UTC storage, UTC parsing, and UTC display guarantees, how it differs from Date and DateTime, supported input formats, and the utility classes (DateUtil, DateParser) that back it.
CurrencyAndUnits
Money and unit values: UnitValue (minor units) versus DoubleUnitValue (major units), Currency.format and minorAmount, the read and write faces of CurrencyView and the objData they need, and why a money column stops derived columns exporting their server value.
i18n
Beginner guide to FOAM i18n: declaring translatable strings with messages:/messageMap in model code, multi-language messageMap fallback rules, and inline localized labels. Runtime Locale rows and localeDAO are covered in the advanced guide.
i18n-advanced
Advanced runtime i18n: how messageMap and localeDAO relate and sync at boot, adding Locale rows, controlling language picker availability via Language rows with an enabled flag, and the message-override lifecycle.
VsSpring Compares FOAM (model-driven, cross-language, context DI, axiom extensibility) vs Spring Boot (annotation-driven, Java IoC container, auto-configuration, Java-only) across architecture, dependency management, and server-side approach.