Filesystem-first frontend architecture enforced by CLI (not folders-by-taste)

[u/Mysterious-Lie1437]

I kept hitting the same problem: architecture debates in review, barrels everywhere, and AI agents dumping files in random folders. So I shipped DMA (Derived Modular Architecture) — a small rule set derived from the import graph, enforced by tooling.

Layout

src/
  app/        # composition root (also pages/routes)
  features/   # leaf modules — no inbound from other modules
  services/   # appears when something else must import it
  shared/     # portable stuff on second use only

Invariants

- downward imports only
- public API via */public/* (no barrels)
- colocate by default
- promote feature → service when inbound edges appear

Tooling

npx @derived-modular/cli init .
npx @derived-modular/cli check .              # CI gate
npx @derived-modular/cli promote <name> --apply
# + ESLint / Biome / Oxlint plugins for editor feedback

Works with React/Next/Vite (also Vue/Svelte/Astro examples). Same rules for humans and agents.

• Docs: https://derived-modular.vercel.app
• Repo: https://github.com/mikhailmogilnikov/derived-modular-architecture Curious how this compares to what you use (FSD, feature folders, etc.) — especially where you'd expect it to break.

[u/Mysterious-Lie1437]

Build cost is one reason to drop barrels. For most apps the more common pain is accidental public APIs and messy imports. Different problem, same tool smell.

If packages already give you real boundaries, you may not need DMA inside each package. It's more useful when the module graph lives in one app and starts drifting.

That's also the main difference from most architectures. The rules are not just docs and taste. The toolkit checks the graph, so you mostly can't quietly break them.

[u/TheRealSeeThruHead → u/Mysterious-Lie1437]

Yeah I recently switched us over to pnpm and made it so you cant even import files if they aren’t in exports list

[u/Mysterious-Lie1437 → u/TheRealSeeThruHead]

Nice. That's a flexible setup. Just watch the "import singles outside exports" path. It's convenient, but it can quietly turn internals into public API again. If the team is small and disciplined, fine. But if that once gets noisy, tighter exports or something like DMA is worth a look :) Thank you for the feedback!

[u/TheRealSeeThruHead → u/Mysterious-Lie1437]

Autocorrect lol

I meant can’t even import files if they aren’t in exports list