mikhailmogilnikov/derived-modular-architecture: Modular frontend architecture enforced by tooling — CLI, linters, and CI, not conventions in chat.

Modular frontend architecture enforced by tooling — CLI, linters, and CI, not conventions in chat. - mikhailmogilnikov/derived-modular-architecture

Summary

Derived Modular Architecture (DMA) encodes frontend module boundaries in folder placement, enforced by a CLI, linters, and CI rather than convention. The architecture targets a src/ layout of composition root (app/, pages/, or routes/), features/, services/, and shared/ with four invariants: downward-only imports, public APIs without barrels (*/public/*), colocation by default, and a second-use rule for shared/. The repo ships a CLI plus editor plugins for ESLint, oxlint, and Biome, and works in single apps and monorepos.

What it is useful for

DMA is useful when a team wants consistent module boundaries that don't depend on tribal knowledge or review-time enforcement. Documented example trees cover Vite + React, Next.js App Router, Astro (pages/), SvelteKit (routes/), and Vue + Vite, so the layout adapts to different router conventions rather than forcing one.

It is useful with AI coding agents. Installing the dma skill makes Cursor, Claude Code, and other hosts follow the same placement rules as the CLI, which is the practical reason for the ai-agents topic.

How engineers can use it

Documented setup:

npm install -D @derived-modular/cli
npx @derived-modular/cli init .
npx @derived-modular/cli check .

Per the README, init scaffolds the missing src/ skeleton, a dma.config.ts, a package.json script, and an AGENTS.md block — strict skip, never overwrite. In a monorepo, run inside the app package (e.g. apps/web).

Commands:

• dma check [path] — hard rules (graph, cycles, inbound predicates); fails CI on errors.
• dma doctor [path] — soft growth signals (exit 0); hints when to promote or split.
• dma promote <module> [--apply] — promotes a feature into services/ and rewrites imports (dry-run by default).

check and doctor accept --format json or --format sarif for CI and code scanning. Monorepo flags include --roots, --include-packages, and --config for explicit roots and library packages.

Editor plugins give fast, file-scoped feedback: @derived-modular/eslint-plugin, @derived-modular/oxlint-plugin, @derived-modular/biome-plugin. The ESLint example softly loads dma.config.* when settings.dma is unset.

For AI agents:

npx skills add mikhailmogilnikov/derived-modular-architecture --skill dma

The README states one documented limitation directly: "Always run dma check in CI — linters are complementary, not a substitute." It also notes services/ should not be created upfront — it appears on first promotion, so scaffold scripts that pre-create every folder would be wrong.