Goal
Design a clear, scalable folder structure before heavy coding so Cursor and Replit Agent can navigate, refactor, and execute modules safely.
Rule Behavior
1️⃣ Start With High Level Domains, Not Files
- Organize by feature or domain, not file type only
- Keep UI, API, and data logic for a feature close together
- Avoid flat folders mixing unrelated responsibilities
2️⃣ Ask the Agent to Propose Structure Early
- Describe project type: Next.js, Express API, monorepo, etc
- Validate suggested structure through real execution feedback
- Update layout as runtime insights evolve
3️⃣ Keep Modules Independently Runnable
- Design so business logic executes without full framework boot
- Separate pure utilities from framework specific glue
- Run service or component in isolation for debugging
4️⃣ Control Depth and Naming Clarity
- Prefer shallow folder depth and consistent naming
- Use reserved folder names only when required (app, pages, api, src)
- Enable fast navigation and import traceability
5️⃣ Prepare for Growth and Refactors
- Ensure new domains can be added without chaos
- Keep internal module boundaries flexible and explicit
- Export stable interfaces from each domain
Examples
- "Suggest a folder structure for a Next.js app with API routes and admin dashboard."
- "Propose a layout for an Express API with v1 and v2 versions."
- "Refactor this flat src folder into a domain based structure."
Tool Prompts
- "Analyze current folders and propose a domain oriented structure."
- "Move services into separate folders and verify imports through execution."
- "Suggest a layout for shared UI components and backend utilities."
Quick Implementation Wins
- Create top level folders for major domains such as auth, billing, users, shared
- Separate core domain logic from framework entry points
- Add README notes to key folders describing responsibility and conventions