Package map

Generated by docs-site/scripts/sync.mjs from the // Package comment of each directory under internal/. To change a line here, change the comment in the Go source.

Dependencies point downward only: modules → platform → kernel.

Business modules

Each one is an HTTP surface over platform packages. Nothing outside a module imports its internal/.

modules/accounting — the HTTP surface of the accounting core: the chart of accounts, journals, tax codes and analytic axes, journal entries, fiscal years and their closing, exchange rates and reconciliation. It is a thin shell over internal/platform/accounting/…, which owns every rule about the books and writes the audit row for every mutation it performs. This package parses requests, calls the platform inside one transaction, and maps its refusals onto HTTP statuses.
modules/activity — the HTTP surface of the user-facing activity feed — distinct from internal/kernel/audit, the append-only statutory trail. See internal/platform/activity’s package comment for the fuller distinction; this package is a thin HTTP shell over that platform package’s Feed function and adds nothing of its own to what “activity” means.
modules/advances — the HTTP surface of the cash advance: internal/platform/advances/… owns every rule and writes the audit row for every mutation it performs; this package parses requests, calls the platform inside one transaction, and maps its refusals onto HTTP statuses.
modules/assets — the HTTP surface of the fixed asset register (Phase 4 O4): internal/platform/assets owns every rule and audit row; this package parses requests, runs one transaction per request (reads included) and maps refusals to RFC 7807. Linking it registers the disposal’s posting rule (boot.go) and the five permissions (permissions.go).
modules/banking — the HTTP surface of bank reconciliation: internal/platform/banking/… owns every rule and writes the audit row for every mutation it performs; this package parses requests, calls the platform inside one transaction, and maps its refusals onto HTTP statuses.
modules/checklist — the HTTP surface of the accounting closing checklist (Workflows > Checklist). It is a thin shell over internal/platform/checklist, which owns every rule and writes each change’s history. Errors are recorded with c.Error and rendered by httpx.Errors; every request runs in one transaction, reads included, because the tenant setting RLS depends on is scoped to the transaction.
modules/consolidation — the HTTP surface of consolidation runs (Phase 6, stage 2): internal/platform/consolidation owns every rule and writes every audit row; this package parses requests, calls it inside one transaction, and maps its refusals onto HTTP statuses. Errors are recorded (c.Error), never written; every request, reads included, runs in a transaction. A refused RUN is not an error but a result (200 with the refusals), so the audit rows the refusal caused in a member’s chain are committed.
modules/crm — the CRM module’s HTTP surface; this file is its permissions. The first segment of every key is the module key, so switching crm off withholds them all.
modules/einvoice — the HTTP surface of e-Invoicing (spec D1): internal/platform/einvoice owns every rule and writes the audit rows; this package parses requests, calls the platform inside transactions, and maps its refusals onto HTTP statuses. Errors are RECORDED (c.Error), never written; every request runs inside a transaction.
modules/expenses — the HTTP surface of the expense claim: the category and allowance-rate vocabulary, the documents that support a claim, and (Tasks 18–19) the claims, groups, lines, attachments and transitions themselves. It is a thin shell over internal/platform/expenses/… and internal/platform/documents/…, which own every rule and write the audit row for every mutation they perform. This package parses requests, calls the platform inside one transaction, and maps its refusals onto HTTP statuses.
modules/exports — the HTTP surface of the table-export column catalogue and presets. Each export kind is registered by its owning module with internal/platform/tableexport; this module only serves the catalogue and saves choices against it.
modules/group — the HTTP surface of the group register (Phase 6): internal/platform/group owns every rule and writes every audit row; this package parses requests, calls it inside one transaction, and maps its refusals onto HTTP statuses. Errors are recorded (c.Error), never written; every request, reads included, runs in a transaction.
modules/hr — the HTTP surface of the HR layer’s employee record (Phase 5 H1): internal/platform/hr owns every rule and writes every audit row; this package parses requests, calls it inside one transaction, and maps its refusals onto HTTP statuses. Errors are recorded (c.Error), never written; every request, reads included, runs in a transaction.
modules/identity — the HTTP surface of the identity system: login, refresh, logout, organization switching, session management and the two provisioning actions.
modules/imports — the HTTP surface of Phase 3’s import tooling: internal/platform/imports owns every rule and writes the audit row; this package parses requests, runs the import inside one transaction (committed for an import, rolled back for a validation), and maps its refusals onto HTTP statuses. It follows internal/modules/banking’s conventions: errors are recorded with c.Error, never written, and every request runs in a transaction.
modules/insight — the HTTP surface of the advisory AI features (internal/platform/insight owns every rule and writes every audit row). A flag is shown to a reader, never acted on: no route here approves, rejects, posts or routes anything. Errors are recorded (c.Error), never written; every request, reads included, runs in a transaction.
modules/integrations — the administrators’ side of the public API and webhooks (design 9): API keys, webhook endpoints and their delivery log, and the organization’s switch. It is NEVER part of the published API: a key can not mint keys or webhooks (no self-service escalation), so none of the keys below is api-grantable and none of these routes is marked x-public-api.
modules/inventory — the HTTP surface of the item master (Phase 4 O1.2): internal/platform/inventory owns every rule and writes the audit row for every mutation; this package parses requests, calls the platform inside one transaction, and maps its refusals onto HTTP statuses.
modules/leave — the HTTP surface of Phase 5 H3’s leave: internal/platform/hr owns every rule and writes every audit row; this package parses requests, calls it inside one transaction, and maps its refusals onto HTTP statuses. Errors are recorded (c.Error), never written; every request, reads included, runs in a transaction.
modules/numbering — the HTTP surface of the Document numbering setting (Plan 12). A thin shell over internal/platform/numbering, which owns every rule: the pattern language, the reset rules, the scheduled change, the starting number and the audit row. This package resolves which document type a request names, runs the call in one transaction, and maps the platform’s refusals onto statuses with a stable code.
modules/orgstructure — the HTTP surface of the org structure: the unit tree, the position tree, who sits in which seat, and the chart that puts the three together. It is a thin shell over internal/platform/orgstruct, which owns every rule about the trees — paths, cycles, the depth cap, the per-organization tree lock, the one-primary-seat constraint — and writes the audit row for every mutation it performs. This package parses requests, calls orgstruct inside one transaction, and maps orgstruct’s refusals onto HTTP statuses. It adds no rule of its own about what a valid tree is.
modules/payables — the HTTP surface of accounts payable: internal/platform/payables/… owns every rule and writes the audit row for every mutation it performs; this package parses requests, calls the platform inside one transaction, and maps its refusals onto HTTP statuses.
modules/payout — the HTTP surface of payout channels (spec 9): channel and registry administration behind payout.channel.manage, and — from Task 7 — a member’s own payout details under /payout/me. A thin shell over internal/platform/payout, which owns every rule, seals every saved detail and writes the audit row for every mutation it performs.
modules/payroll — the HTTP surface of Phase 5 payroll P1: internal/platform/payroll owns every rule and writes every audit row; this package parses requests, calls it inside one transaction, and maps its refusals onto HTTP statuses.
modules/pettycash — the HTTP surface of the petty-cash float: opening and closing floats, reading them and their movements (this task), and — Tasks 17-18 — the spends, top-ups and close-outs a float moves through. It is a thin shell over internal/platform/pettycash/…, which owns every rule and writes the audit row for every mutation it performs. This package parses requests, calls the platform inside one transaction, and maps its refusals onto HTTP statuses.
modules/receivables — the HTTP surface of accounts receivable: internal/platform/receivables/… owns every rule and writes the audit row for every mutation it performs; this package parses requests, calls the platform inside one transaction, and maps its refusals onto HTTP statuses.
modules/reports — the HTTP surface of the read-only reporting layer: the trial balance, profit and loss, balance sheet and general-ledger detail, each derived from the posted ledger (internal/platform/reporting/…), plus (Task 15) requesting, listing and downloading exports of them. It is a thin shell, like internal/modules/accounting:
modules/search — global search (GET /v1/search): one query, answered per record kind by the module that owns the kind, through its contract.go. This package owns none of the visibility rules — each group is what that kind’s own list would serve the caller — and only validates the request and shapes the answer.
modules/taxreturns — the HTTP surface of the periodic tax return engine: internal/platform/taxreturn owns every rule and writes the audit row for every mutation it performs; this package parses requests, calls the platform inside one transaction, and maps its refusals onto HTTP statuses.
modules/trade — the HTTP surface of procurement and sales (Phase 4 O3): requisitions, purchase orders, goods receipts and purchase returns under /procurement, quotations, sales orders, deliveries and sales returns under /sales — each group behind its own module-install switch (R-O3-14). internal/platform/trade owns every rule and writes every audit row; this package parses requests, calls it inside one transaction and maps its refusals onto HTTP statuses.
modules/workflow — the HTTP surface of the workflow engine: the definition editor’s API (Plan 10 builds the screen), delegations, and the decision log. It is a thin shell over internal/platform/workflow, which owns every rule. It exposes no transition endpoint: moving a document is its owning module’s route (Ruling 14).

Platform

Shared capabilities modules build on: workflow, posting, numbering, documents, i18n.

platform/accounting — the posting engine (spec 10.3): the registry of posting rules and the posting.Poster that turns a workflow transition into journal entries, inside the transition’s own transaction.
platform/activity — writes and reads the user-facing feed.
platform/advances — owns the cash advance: an employee is paid out before a trip or a purchase, on the promise that receipts come back afterward (spec 7.1). An advance is not an expense claim — nothing is charged to an expense account until it is acquitted — and it is not a loan either: the only way to close one is to account for every last cent of what was handed out, either against a receipt or by giving the unspent balance back (Ruling A4).
platform/assets — the fixed-asset register (Phase 4 operations design O4): asset classes, assets registered from what already posted their cost, monthly depreciation runs, disposals, reports, and the register-to-ledger integrity check.
platform/attachments — binds uploaded documents to the records they support: invoices, receipts, payments and the trade-chain documents. One link table, one binder; the kinds below say which table a record lives in and who may read its attachments.
platform/banking — bank accounts, statement import, matching and bank reconciliation (spec 2026-09-27). It is not the §10.6 reconciliation set (internal/platform/accounting/reconcile).
platform/checklist — the accounting closing checklist: a run is a table of sections and rows, with columns an accounting manager can rename and extend, a Performed Date per row, and a history of every change. A template is a run with is_template = true, so starting a run is a copy.
platform/company — the one company profile row an organization has.
platform/consolidation — produces a group’s consolidated position (Phase 6, stage 2; docs/superpowers/specs/2026-10-03-consolidation-runs-design.md): an owner-initiated, immutable run at one date that reads each member’s books through the allowlisted, consent-checked, audited functions of migration 00942, maps them to the owner’s group chart, translates them to the presentation currency with the rates frozen into the run, eliminates inter-company balances, investments, dividends and unrealized profit into owner-side tables, attributes non-controlling interests and associates, and records closing checks that decide whether the run is provisional or final-capable.
platform/countrypack — the country-pack interface, the generic seeder that turns a pack into rows through the chart package (spec 11, narrowed per Ruling R28), and provisioning steps 70–72 that seed a newly provisioned organization’s chart of accounts, journals and tax codes from the pack named by its company profile’s country code.
platform/crm — the CRM’s platform layer: its schema and workflow graphs. CRM reuses existing workflow semantics only (CD-3); no CRM state posts.
platform/customfield — user-defined fields (platform customization design C2): typed fields an organization adds to customers, suppliers and sales and purchase documents, labelled in en/ms/zh like a payout channel’s field_schema. Definitions live here; values live on each record (custom_fields jsonb) and are checked by Resolve, which each entity’s own create and update calls, so the screen, the API and the import all pass through the same rules.
platform/documents — owns objects: presigned upload tickets, verification by content hash, thumbnails and download URLs. Store is the only way this codebase reaches document bytes (wave-2 contract §4, Ruling R30-R33); the only adapter is documents/s3store, and tests use documentstest.MemStore.
platform/einvoice — submits issued documents to a tax authority’s e-Invoice system and tracks them: the country-neutral half (spec D1). The authority’s own rules, codes, encoding and HTTP client live in the country pack and meet this package at Codec and Client.
platform/expenses — owns everything with an expense rule in it: the expense category registry (the Phase 0 table, extended with its GL account and its tax-record policy), the date-effective mileage and per-diem rates, and — as later tasks land — claims, lines, attachments, submission checks, settlements and the posting rules behind them.
platform/exportpreset — keeps saved column choices for table exports: private to their owner unless shared with the organization, and only ever changed by their owner. Whether the columns exist in a kind’s catalogue is the caller’s check (tableexport.Resolve); this store only bounds their number.
platform/group — the group register (Phase 6, stage 1 of consolidation; docs/superpowers/specs/2026-10-03-group-register-design.md): a register, kept by one organization (the group’s owner), of the legal persons in a group, who holds what share of whom and when, and who the beneficial owners are. The register tables carry the owner’s org_id and the standard org_isolation policy. A holding is never edited: ChangeShareholding ends the current row on the change date and inserts the new one (Ruling GR-1), so what a past date looked like can always be reproduced.
platform/hr — the HR layer’s employee record (Phase 5 H1, docs/superpowers/specs/2026-09-30-hr-layer-design.md): one employee row per employee party, separate from the login member (HD-1), with an append-only lifecycle (employee_event) from which hire date, employment type, last day and status are derived by employee_spell() — never stored (Ruling H1-1). Recording a last day is refused while the person holds an open advance or petty cash float, unless an Owner who is not the requester overrides it (HD-6).
platform/i18n — resolves the caller’s locale and loads translated names.
platform/identity — no package comment
platform/imports — Phase 3’s import and migration tooling (docs/superpowers/specs/2026-09-29-import-tooling-design.md, lane M1): a CSV or XLSX file, its columns mapped to a kind’s fields, saved row by row through the same functions the screens use.
platform/insight — the three advisory AI features of docs/superpowers/specs/2026-10-03-ai-features-design.md: claim flags (claimflags), spend forecasts (forecast) and natural-language report search (nlreport), plus what they share: the per-feature mode, the run record, flag status and feedback.
platform/inventory — the item master (Phase 4 O1.2, docs/superpowers/specs/2026-09-30-operations-design.md): items, their units of measure, categories and locations. O2 adds the stock ledger here.
platform/moduleinstall — per-tenant module install (platform customization design C1): which optional modules an organization uses. The code is linked in every binary either way (the modules import one another); “not installed” means its permissions are held by no one (member.Permissions leaves them out, so every route refuses and the web hides it) and its route group answers module_not_installed. Switching a module off never deletes data; switching it back on restores it as it was.
platform/notifications — the header bell (spec 2026-09-26-notifications-design.md): a member’s own list of pointers to records that need or concern them. A row holds no prose — the client renders the line from Kind, RecordKind and Reference — and is operational, not a record: what happened lives in the decision log, audit_log and the comment itself.
platform/numbering — issues human-facing and statutory document numbers, with Issue: it allocates and renders in one call, so a module cannot format a number its own way.
platform/onboarding — creates an organization and its first Owner, in two phases (two-phase onboarding design, 2026-10-09).
platform/opsjobs — runs the operator console’s work in the worker: checks and actions that touch an organization run here, inside that organization’s own tenant transaction, never in the console (operator console design §3.5).
platform/orgstruct — owns the two trees approval routing depends on: the org unit tree (structure) and the position tree (seats), plus the assignments that put people in seats over time.
platform/payables — accounts payable (spec 2026-09-26 AP design): the supplier role on party, purchase invoices, supplier credit notes and supplier debit notes (one table, kind = the workflow kind), supplier payments, the append-only allocation of payments and credit notes to invoices, and the aging derived from them, and payment batches (spec 2026-09-27 payment batches), which group submitted payments into one bank file and post nothing. Every posting goes through accounting’s posting engine: this package registers rules keyed (kind, semantic) and never writes a journal line (spec §10.3).
platform/payout — owns payout channels (spec 9): the org-defined channel definitions, their field_schema and GL binding, the registries a registry_ref field points at, members’ saved payout details, and the settlement snapshot a claim freezes.
platform/payroll — Phase 5 payroll P1 (docs/superpowers/specs/2026-10-01-payroll-p1-design.md, plan docs/superpowers/plans/2026-10-01-phase-5-payroll-p1.md, Rulings PD-7–PD-30): salaries, pay item types and recurring items, the monthly run (a snapshot: each preparation writes a new calculation generation; submission freezes it), the payroll_run workflow that posts by semantic tags, and the payslip workflow that a payment batch pays (C4’s pattern).
platform/pettycash — spec §8: floats, the movement ledger, spends, top-ups, replenishments and close-outs, and the settlement API internal/platform/expenses calls (wave-3 contract §2.2). It never imports internal/platform/expenses.
platform/posting — the seam between the workflow engine (Plan 3) and the accounting core (Plan 4), spec §5.5 and §10.3.
platform/printing — the document layout designer (platform customization design C4): per organization and document kind, which optional header lines and table columns print, the title and label language, footer notes and the logo. A layout is validated configuration applied by this package’s renderers, never a template (Ruling L-1), and the statutory content of every document prints whatever the layout says.
platform/provisioning — seeds a newly created organization.
platform/receivables — accounts receivable (spec 2026-09-27 AR design): the customer role on party, sales invoices and customer credit notes (one table, kind = the workflow kind) shaped for MyInvois and frozen once issued, customer receipts, the append-only allocation of receipts and credit notes to invoices, and the aging and statements derived from them. Every posting goes through accounting’s posting engine: this package registers rules keyed (kind, semantic) and never writes a journal line.
platform/registry — the rules every org-configurable lookup table shares, in one place so that adding a fourth registry cannot quietly get one of them wrong.
platform/reimbursement — decides how an amount spent in another currency becomes the base amount an organization reimburses or books (spec 2026-10-08-claim-foreign-currency-basis-design). It is shared by every record that converts a claimant’s spend: an expense claim line and an advance acquittal today, a petty-cash spend or a supplier-card expense tomorrow.
platform/reporting — the one query layer spec §10.7’s reports are built on (Plan 9). Every figure it produces is a SUM over posted journal_line base amounts, or over analytic_distribution.base_amount under an analytic filter — never a recomputation from a percentage, a rate, or a transaction-currency amount (Ruling R3).
platform/savedreport — keeps custom report definitions (platform customization design C3, Ruling R-2): private to their owner unless shared with every holder of reports.read, and only ever changed by their owner. The report itself is reporting.Custom; package reporting never writes, so the saved definitions live here.
platform/tableexport — the shared half of “export this list as a spreadsheet”: a column catalogue per export kind, a user’s choice of columns against it, and the CSV/XLSX writer. It reads no records: each owning module supplies rows, because what a caller may see is that module’s rule.
platform/taxrecord — the database-free half of the Malaysian e-Invoice tax record (spec 6.7): the supplier TIN and e-Invoice UUID shapes, and the document-basis discriminator recording why a line’s, an acquittal’s or a petty-cash spend’s supporting document is acceptable.
platform/taxreturn — the periodic indirect-tax return engine (spec D1): the taxable-period arithmetic and, in later tasks, the figures that fill a countrypack.TaxReturnDef’s fields from AR’s tables. It reads AR’s tables read-only — sales_invoice, sales_invoice_line, customer_receipt, ar_allocation — and never writes them.
platform/telegram — the notification bot (docs/superpowers/specs/2026-10-07-notification-settings-telegram-design.md): per-member notification settings, the one-time link between a member and a Telegram account, the outbox and its River worker, and the webhook that turns an Approve or Reject tap into the same workflow move the web makes. Telegram is an input device, never an authority: every move runs as the linked member through the engine, which answers who may do what.
platform/trade — the document chain (Phase 4 O1.1, docs/superpowers/specs/2026-09-30-operations-design.md): requisitions, orders, goods receipts, purchase returns, quotations, sales orders, delivery orders, sales returns and stock adjustments on one trade_document / trade_line pair (OD-5), linked line to line. Procurement and sales (O3) and stock (O2) build on it; sales adds nothing to it.
platform/webhooks — the outbound half of the public API (design docs/superpowers/specs/2026-10-03-public-api-webhooks-design.md section 7): a transactional outbox over a small catalogue of domain events, signed deliveries to endpoints an administrator registered, and the log of both.
platform/workflow — the workflow engine (spec 5): per-organization, per-kind, versioned definitions; gates and grants with amount floors; grantee resolution over the org structure; delegation and escalation; and the transition function that posts through internal/platform/posting in the same transaction and writes the immutable decision log.

Kernel

Tenancy, money, audit, errors, the event bus. Imports nothing above it.

kernel/audit — writes the compliance trail.
kernel/authn — the identity types the HTTP edge and the token package both need. It lives in kernel, not platform/identity/token, because a later task adds HTTP middleware in internal/kernel/httpx that must name this type, and internal/kernel is forbidden from importing internal/platform (see internal/kernel/layering).
kernel/clock — the single definition of “now” and “today” for the whole system.
kernel/config — reads process configuration. Every variable read here must appear in .env.example; envexample_test.go enforces that.
kernel/db — no package comment
kernel/errors — the single translation from internal failures to the HTTP surface. Handlers never inspect driver errors; each module translating its own is how the same failure ends up with three different status codes.
kernel/eventbus — delivers in-process domain events.
kernel/httpx — the HTTP edge: the middleware chain and the router.
kernel/jobs — the one place River is configured (Plan 9 Rulings R14–R16).
kernel/keyring — seals a secret that has to be recoverable (AES-256-GCM, the id of the sealing key stored beside the ciphertext). It was internal/platform/payout’s, moved here so the webhook signing secrets can share the mechanism without sharing a key: each use has its own keyring instance and its own environment variable, so their rotations never couple (public API design D13).
kernel/layering — no package comment
kernel/listquery — builds the search, sort and keyset-paging fragments the list endpoints share. Expressions passed in are trusted SQL written in the module; nothing from a request is ever interpolated, only bound.
kernel/locale — resolves the caller’s locale from a request. It is a cross-cutting, database-free primitive — no domain knowledge, no I/O — which is why it lives in kernel rather than platform. Loading translated rows from the database is platform/i18n’s job, not this package’s.
kernel/money — the only representation of a monetary value in the system.
kernel/ratelimit — a token-bucket limiter for the public API (design 6): per credential, per organization, and per source address for failed key authentication.
kernel/recordtext — the script rule for record-bearing free text (spec 11A.3): a statutory record is kept in English or Bahasa Malaysia, so Chinese, Japanese or Korean script is refused wherever it appears in one. zh remains a UI locale; it is never a record locale.
kernel/tenancy — carries the active organization for a request.
kernel/vocab — no package comment