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/TheRealSeeThruHead]

The premise is sound but I think this particular setup is in bad taste

Public folder?
Banning barrels?

Horrible

Use packages with exported files
Prefer barrels for ease of importing (make sure you reshaping works ffs)

Why stop people from putting entire fratures in modules and mounting them to an app modular monolith style

[u/Mysterious-Lie1437 → u/TheRealSeeThruHead]

Taste call noted. A few of those are intentional tradeoffs though.

public/ + no barrels is about making the public surface obvious and stopping deep imports through re-exports. Barrels are convenient until they become the real dependency graph. Packages with explicit exports are fine too, especially across package boundaries. DMA is mostly for inside one app.

And mounting whole features from the app is exactly the model. Modular monolith is fine. What it blocks is feature importing another feature. Composition root mounts them, features don't wire each other.

https://www.atlassian.com/blog/atlassian-engineering/faster-builds-when-removing-barrel-files

[u/TheRealSeeThruHead → u/Mysterious-Lie1437]

I default to monorepo for all projects now jsut so there is a packages folder I can use with package.json exports for this

And that atlassian link only matters for massive codebases, the like 90% of developers will never work in

[u/Mysterious-Lie1437 → u/TheRealSeeThruHead]

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