Building a business system on DODIL: the map
For the agent building sales, HR, contracts, invoicing or the books for a customer, whatever they call it ("an app", "a system", "something to replace the spreadsheet"). Read this page, then one card per phase, in order. Each card is short: numbered steps, an example, "done when".
The mindset, in one paragraph
Most modules already exist as bricks: public git repos on erp-platform, pinned at release tags.
You compose them for this customer; you do not rewrite them. Everything is customizable, at three
depths: 1 configure (rows, through the brick's use cases), 2 extend (a capability in the
customer's own small brick), 3 own (a fork of the brick in the customer's org, its intent
recorded and re-applied on each upgrade). A small foundation is kept and refused if broken:
stable ids (process and step keys, APQC PCF ids, use-case names), shared keys and data integrity,
the security model, and erp-platform itself. Best practices are defaults with warnings: a
deviation is shown, signed, then built. The customer sees their business as BPMN generated from
the configuration; their stories are paths on it; the signed diagram is the contract.
Phases 0-3 are documents. The customer signs before any code.
| # | Phase | Produce | Tool | Card |
|---|---|---|---|---|
| 0 | Frame | a scope note: modules, first module, how involved they want to be | dodil ignite app list, ERP_*.md in their repo | dodil://erp/phase/frame |
| 1 | Discover | candidate modules, bricks and tags, the reference process | index.json, modules/<id>/module.yaml reference.repos | dodil://erp/phase/discover |
| 2 | Show (understand) | actors, stories with Given/When/Then and a path each, entities, master data | uvx --from git+https://git.dodil.io/dodil/erp-platform.git@v0.7.3 erp-compose process (HR: show_playbook_bpmn), /modules/<id>/process.bpmn | dodil://erp/phase/show |
| 3 | Fit (design) | ERP_<MODULE>.md and the change list, each item with its depth | modules/template.md; HR: config/hr.calls.yaml + erp-compose process | dodil://erp/phase/fit |
| 3s | Sign off | signoff/<module>.json + Processes/Scenarios/Deviations rows | uvx --from git+https://git.dodil.io/dodil/erp-platform.git@v0.7.3 erp-compose signoff record | dodil://erp/phase/signoff |
| 4 | Build | a customer repo composing the bricks; rows; own brick or fork if signed | uvx --from git+https://git.dodil.io/dodil/erp-platform.git@v0.7.3 erp-compose init <module> | dodil://erp/phase/build |
| 5 | Test | the composition's own tests/, scenarios in process and live | pytest, erp-scenarios run | dodil://erp/phase/test |
| 6-8 | Deploy | test copy then live; pool, roles, SA; a real sign-in | erp-compose plan/migrate, git push, dodil ignite invoke | dodil://erp/phase/deploy |
| 9 | Operate | findings against the signed process | process mining not built yet | dodil://erp/phase/operate |
| 9c | Change | v2 of the process: diff, impact with counts, migration, new sign-off | erp-migrate; up/down not built yet | dodil://erp/phase/change |
The rules that hold in every phase
- Interactive by default. One topic per turn, one to three questions, each with choices and a recommended default. Say back what you recorded.
- The repo remembers, not you. Start every session by reading every
ERP_*.md(Status, People, Change requests, Decisions) and open with a three-line "where we are". - Test copy first; live only on an explicit "go live".
<customer>-devand<customer>. Local.envpoints at the test copy only. Say which one you touch, every time. - Show it on localhost before anything goes live.
- An approval is words the customer typed, naming the version. Never your summary of one.
Working signed out
Phases 0-5 need no DODIL login: the bricks clone anonymously, and the composition runs in process
on SQLite. Do not create buckets, pools or apps before phase 6. If a dodil command says you are
not signed in, do not try to sign in from a headless session: ask the person to run
dodil auth login, and carry on with what needs no login.
Facts to copy, not re-derive
- Compose with one command, never by hand:
erp-compose init <module>(the build card) clones the bricks at their tags (never branches) intobricks/, makes.venv, writesrequirements.txt,compose.yamland the composition test, and runs the checks. ReadREADME.mdandAGENTS.mdof each brick before writing anything. - The composition ships its own test (
modules/test_composition.py→tests/): the bricks' suites prove the bricks, not your assembly (lab, 2026-10-17). - Claims are a plain
INSERT: under concurrency one writer wins and the rest get23505. Never claim with an upsert (tables 0.2.1, measured 2026-10-17). - 64-bit ids travel as JSON strings (
Brick(ids_as_strings=True)); JavaScript rounds past 2^53. - No lost updates: an edit sends the version it loaded (
If-Match: "3"); stale is 409. - TLS:
sslmode=require(verify-full+sslrootcertin production) andbolt+s://; neverpreferorneo4j+s://. - Natural keys, no SERIAL; money
NUMERIC(18,2);DELETEneeds aWHERE; no read-your-writes inside an open transaction. - Verify a deploy with
POST /(dodil ignite invoke), not the public URL: a 401 there proves only that the gateway is up.
Where the rest is
Read any of these as an MCP resource dodil://erp/file/<path>, or from git.dodil.io/dodil/erp-method:
modules/lifecycle.md (the method with its reasons), modules/pattern.md (the anatomy of a module
and a brick), modules/template.md (ERP_<MODULE>.md, v3), modules/module.template.yaml (a new
spec), modules/shared.yaml (keys that cross modules), index.json (everything, by tag).
Module catalogue and specs: dodil://erp/modules/index.json, dodil://erp/modules/<id>/spec.yaml.