Structure React Applications — AI Agent Architecture Skill
by Moussa Saidi
$19+
Stop letting components, hooks, services, and utils become the architecture.
Large React applications rarely become difficult because they need one more folder. They become difficult when ownership is unclear, business rules leak into components, HTTP payloads spread through the UI, and every generic directory becomes a dumping ground.
Structure React Applications gives your AI coding agent an opinionated decision framework for organizing and changing production React + TypeScript codebases.
It teaches the agent to reason about the architecture before it moves files: who owns the behavior, what the module may depend on, what it exposes publicly, and how far a future change should propagate.
WHAT THE SKILL GUIDES YOUR AGENT TO DO
• Organize around user capabilities and business ownership—not file types.
• Separate application composition, feature workflows, domain rules, and shared foundations.
• Keep domain logic independent of React, routers, browsers, query caches, and HTTP response shapes.
• Put API transport mechanics and product-specific adapters at the correct boundaries.
• Expose small public module APIs instead of private deep imports.
• Maintain one-way dependency flow: app → features → domains → shared.
• Promote code to shared only when its behavior, name, and ownership are genuinely stable.
• Place tests by ownership when the repository permits them.
• Refactor one changing vertical slice at a time instead of proposing a cosmetic rewrite.
NOT ANOTHER FOLDER-TREE TEMPLATE
A folder tree cannot decide whether canCancelOrder belongs beside a dialog, in an order domain, or in a generic utility file. This skill includes the decision criteria behind the structure, so the agent can adapt it to Next.js, React Router, Vite, an established monorepo, or an imperfect legacy codebase.
Repository instructions and framework conventions still win. The skill tells the agent to inspect the existing code, preserve unrelated changes, avoid empty abstractions, and state conflicts before acting.
WHAT YOU RECEIVE
• Production-ready SKILL.md workflow.
• Detailed architecture reference with a folder structure and placement matrix.
• Feature-owned vertical-slice and framework-independent domain examples.
• API adapter, DTO mapping, and public module API examples.
• Cross-feature composition and incremental migration guidance.
• Architecture review findings with severity levels.
• Buyer installation guide with ready-to-use prompts.
• Individual commercial license for unlimited personal, employer, and client projects.
No runtime package, API key, dependency, or build step is required.
WORKS WITH CODEX AND CLAUDE CODE
Both products support SKILL.md skills with supporting files and automatic discovery. Invoke $structure-react-applications in Codex or /structure-react-applications in Claude Code. Other agents can use the Markdown workflow when they support skills or project instructions.
USEFUL FOR
• Senior React engineers and technical leads using AI coding agents.
• Teams starting a production React or Next.js application.
• Features spanning UI, state, API calls, and business rules.
• Reviews of deep imports, dependency cycles, leaking transport types, and unclear ownership.
• Incremental modernization of codebases with generic top-level folders.
EXAMPLE PROMPT
Use the Structure React Applications skill to add the cancel-order capability as one complete vertical slice. Explain its owner, public API, and allowed dependency direction before editing. Preserve the repository’s existing conventions and avoid a broad restructure.
LICENSE
One purchaser may use and privately modify the skill across unlimited personal, employer, and client projects. Sharing, publishing, reselling, sublicensing, or redistributing the original or modified skill files is not allowed. Each additional direct user needs a separate license. Outputs created with assistance from the skill remain yours, subject to applicable law and third-party rights.
ABOUT THE AUTHOR
I’m Moussa Saidi, a hands-on React technical lead. This skill operationalizes the architecture decisions I use to make large React applications easier to understand, safer to change, and easier for teams to own.
Read the free architecture guide:
https://www.moussasaidi.dev/en/blog/how-i-structure-a-large-react-application
Questions or team licensing: contact@moussasaidi.dev
Independent product by Moussa Saidi. Not affiliated with or endorsed by OpenAI, Anthropic, Meta, React, or any AI-agent vendor.
Review on Product Hunt