Koder Monorepo — Taxonomy

Canonical reference of the monorepo's directory structure and naming rules. This document describes the agreed-upon target state of the taxonomy, as decided by RFCs 003–009. The on-disk migration is executed in sweeps; the migration status section tracks where each rename stands.

For the why behind each level, read the RFCs in rfcs/. This document is the operational reference; the RFCs are the design history.

1. The six levels

The taxonomy applies a single criterion per level, in the spirit of Linnaean classification. Each level has a precise question that determines where a thing belongs.

Below L5 is build-tool territory (go.mod, pubspec.yaml, Cargo.toml, …), governed by each language's package manager — outside this taxonomy.

2. L1 — the five Domains

koder/
├── products/         ← consumed by direct interaction (UI/DX, brand)
├── services/         ← consumed by API call (network)
├── engines/          ← consumed by embedding (import + execute locally)
├── infra/            ← consumed by operation (deploy + configure)
└── meta/             ← consumed by reading (humans, not runtime)

3. L2 — Areas inside each Domain

Each Domain applies a local L2 criterion. The criterion varies by Domain, but the level of abstraction (a thematic grouping of Sectors) is constant. See RFC-004 for the per-Domain rationale.

products/ — split by audience model

products/
├── horizontal/       ← B2C horizontal — any user, any industry
├── vertical/         ← B2B vertical — industry specialist
└── dev/              ← B2D — developer / technical operator

Renamed from suite/ per RFC-007. The marketing brand "Koder Suite" is independent of this folder name.

services/ — split by functional domain

services/
├── foundation/       ← cross-product primitives (id, billing, payments, moderation, ads)
├── ai/               ← AI services (gateway, runtime, recsys, voice, agents, RAG)
└── media/            ← audio/video processing services (transcoding, streaming)

engines/ — split by functional domain

engines/
├── kodec/            ← audio/video codec (lib, C API, WASM, bindings, CLI)
├── lang/             ← Kode language: compiler, runtime, stdlib, KMD
└── sdk/              ← client SDKs (external) + internal libs (koder_kit, koder_ipc, …)

infra/ — split by infrastructure function

infra/
├── net/              ← network, security, edge, DNS, mesh, firewall
├── data/             ← databases, queues, search, blob, pipelines
├── observe/          ← APM, logs, metrics, alerting, uptime
└── linux/            ← Koder Kodix distro and desktop environment

meta/ — split by artifact type

meta/
├── brand/            ← visual identity: logos, palettes, fonts, guidelines
├── docs/             ← Stack normative documentation (this directory)
├── sites/            ← web presence (institutional, catalog, Area landings)
└── context/          ← agent infrastructure configuration (Claude Code)

The split between meta/docs/ (normative documentation) and meta/context/ (agent operational configuration) is codified by RFC-009.

4. L3 — Sectors

A Sector is a unit of product/service identity within an Area. It has:

1. a proper name (distinct from any other Sector in the same Area),
2. an independent lifecycle (can launch, pause, or be discontinued without

   forcing the same on sibling Sectors),

3. at least one concrete or firmly planned distribution form (L4).

A customer contracts a Sector — not a Domain or an Area. See RFC-005 for edge cases and rules.

Examples: products/horizontal/kmail, services/foundation/id, engines/sdk/go, infra/data/kdb, meta/sites/stack.

5. L4 — Distribution forms (closed vocabulary)

Inside each Sector, the artifacts are organized by how they reach the consumer. The vocabulary is closed and uniform across the entire monorepo.

Semantic structure

The L4 forms cluster along the same consumption axis used at L1:

backend/                            ← consumed by API
app/{mobile,android,desktop,tv,web,cli,tui} ← consumed by direct human interaction
engine/                             ← consumed by embedding (engines/ Domain only)
landing/                            ← consumed by reading
<brand>/                            ← brand-packaged variant

Adding a new L4 form

Requires (1) a distinct platformruntimepackaging combination, (2) at least three Sectors using it, and (3) a formal RFC amendment. See RFC-006 §3.4.

L4 vs. variants

Each L4 directory is a source of variants, not the variant itself. A variant is the executable instance for a specific combination of surface × target × form factor (where surface ≈ L4). A single app/desktop/ produces three variants — <sector>-desktop-linux, -macos, -windows. A single app/mobile/ produces two — -mobile-android, -mobile-ios. The L4 is the source, the variant is the output. Full vocabulary: specs/variants/taxonomy.kmd.

6. L5 — Language conventions

Inside each L4, contents follow the idiomatic conventions of the canonical language and framework chosen for that form.

L5 conventions live as specs and policies in meta/docs/stack/specs/ and meta/docs/stack/policies/. RFC-008 indexes which spec governs which L4. See the L5 spec/policy index.

7. Sector internal layout (canonical examples)

Consumer product Sector (products/)

products/horizontal/kmail/
├── backend/                ← Go server
├── app/
│   ├── mobile/             ← Kroma Android+iOS (Flutter legacy → stack-RFC-019)
│   ├── desktop/            ← Kroma Linux+macOS+Windows (Flutter legacy)
│   └── web/                ← Webmail (Kroma Web; Flutter Web legacy)
├── raven/                  ← B2B brand variant
│   ├── backend/
│   └── landing/            ← raven.koder.dev
└── landing/                ← kmail.koder.dev

Service Sector (services/)

services/foundation/id/
├── backend/
├── app/
│   ├── web/                ← admin console
│   └── cli/                ← `kid …` admin CLI
└── landing/                ← id.koder.dev

Engine Sector (engines/)

engines/lang/koda/
├── engine/                 ← language compiler/runtime/stdlib
├── app/
│   ├── cli/                ← `kode build`, `kode run`
│   └── tui/                ← interactive REPL
└── landing/                ← kode.koder.dev

engines/kodec/kodec/
├── engine/                 ← multi-language by L5 sub-tree
│   ├── core/                   ← canonical implementation
│   ├── c/                      ← C ABI binding
│   ├── wasm/                   ← WASM build
│   ├── go/                     ← Go binding
│   ├── python/                 ← Python binding
│   └── rust/                   ← Rust binding
└── landing/                ← kodec.koder.dev

Infra Sector (infra/)

infra/data/kdb/
├── backend/                ← database server
├── app/
│   └── cli/                ← `kdb` admin tool
└── landing/                ← kdb.koder.dev

Meta Sector — sites (meta/sites/)

meta/sites/
├── stack/                  ← www.koder.dev (Koder Stack home)
├── company/                ← company.koder.dev (institutional)
├── platform/               ← platform.koder.dev (product catalog)
└── areas/                  ← landings for each L2 Area
    ├── horizontal/             → horizontal.koder.dev
    ├── vertical/               → vertical.koder.dev
    ├── dev/                    → dev.koder.dev
    ├── foundation/             → foundation.koder.dev
    ├── ai/                     → ai.koder.dev
    ├── media/                  → media.koder.dev
    ├── data/                   → data.koder.dev
    ├── observe/                → observe.koder.dev
    └── linux/                  → linux.koder.dev

8. Placement decision tree

For any new component, walk the tree top-down:

L1 — How is it consumed?
  Direct interaction (UI/DX)?         → products/
  API call (network)?                 → services/
  Embedding (import + execute)?       → engines/
  Operation (deploy + configure)?     → infra/
  Reading (humans)?                   → meta/

L2 — Apply the local Area criterion of the chosen Domain.
  products/   → audience model (horizontal / vertical / dev)
  services/   → functional domain (foundation / ai / media)
  engines/    → functional domain (kodec / lang / sdk)
  infra/      → infrastructure function (net / data / observe / linux)
  meta/       → artifact type (brand / docs / sites / context)

L3 — Does it have its own market identity, lifecycle, and at least one
     distribution form? → it is a Sector. Otherwise it lives inside an
     existing Sector at L4 or below.

L4 — Use the closed vocabulary:
  Server          → backend/
  Human-facing    → app/{mobile,android,desktop,tv,web,cli,tui}/
  Embeddable      → engine/  (engines/ Domain only)
  Landing page    → landing/
  B2B variant     → <brand>/

L5 — Follow the canonical language and framework for that L4.
     Reference the spec or policy that codifies the convention.

9. Engine + product pairs

Multi-tenant Koder SaaS often ships as two named products: a B2B white-label engine and a B2C flagship product on top of it. They share the same Sector (the consumer name) and split at L4 via the brand variant folder. See engine-product-pattern.md for the catalog.

10. Migration status

The taxonomy was designed in nine RFCs (003–009). The on-disk migration was executed in sweeps on 2026-04-29 (commits a07dab604..4b2acba61). Transitional symlinks at the monorepo root preserve old paths while references are updated incrementally; they will be removed in a final cleanup sweep once all references resolve to the canonical locations.

Deferred sweeps — rationale

L4 engine/ → backend/ (RFC-002): All 51 Sectors that have an engine/ directory already have a backend/ directory as well (a prior session set up the new structure but didn't remove the old). Each Sector needs per-case analysis to decide whether engine/ is duplicate (remove), parallel work-in-progress (merge into backend/), or something distinct (rename specifically). Out of scope for an automated sweep.

L4 lib/ → engine/ (RFC-006 update): Sectors in engines/ are already canonical language projects (engines/sdk/go/ is a Go module, engines/lang/koda/ is a Cargo workspace, etc.). Wrapping their contents in an explicit engine/ directory adds nesting that fights language conventions (where lib/ in Dart means the source root, not a library distribution form). The pragmatic interpretation is that the Sector itself acts as the L4 engine/ form when only one distribution exists. The explicit wrapper is added only when a Sector has multiple L4 forms (e.g., engine/ + app/cli/). This decision may be revisited in a future RFC.

Transitional symlinks: kept until references in module READMEs, go.mod replace directives, CI configs, deploy configs, and other docs are updated to canonical paths. Removal is mechanical once references are clean.

11. Related references

• RFCs (history of decisions): docs/stack/rfcs/
• Vocabulary (canonical terms): vocabulary.md
• Area + Sector catalog (current instances): areas.md
• Engine + product pattern (registry of pairs): engine-product-pattern.md
• Module catalog: module-catalog.md
• Per-module deep-dives: modules/
• Specs (normative L5 rules): specs/ (post-RFC-009 migration: meta/docs/stack/specs/)
• Policies (behavioral guidance): policies/ (post-RFC-009 migration: meta/docs/stack/policies/)