Code Structure Architect

Code Structure Architect

When to use this skill

• When the user asks to "set up the folders" for a new project.
• When the user asks to "clean up" or "refactor" a messy directory.
• When the user asks "where should I put this file?".
• When starting any new Next.js, Flutter, Python, or standard web project.

Core Philosophy: Feature-First

We strictly follow Feature-First Architecture (Vertical Slicing). Code that changes together stays together.

• Bad (Type-First): /​components, /​hooks, /​services (Separates logic by file type).
• Good (Feature-First): /​features/​auth, /​features/​dashboard (Groups explicitly by user value).

Workflow

1. Scaffolding (New Project)

1. Identify Framework: Detect if it's Next.js, Flutter, Python, etc.
2. Apply Template: Use the specific directory map below.
3. Create Core: Generate core/ (shared logic) and features/ (business logic) folders immediately.

2. Refactoring (Cleanup)

1. Audit: List all files.
2. Group: Identify "features" (e.g., "Login", "Profile", "Feed").
3. Move:
   • Move generic UI (buttons, cards) -> components/​ui/.
   • Move shared utilities (dates, formatting) -> utils/.
   • Move feature logic -> features/<feature-name>/.
4. Export: Create barrel files (index.ts / barrier.dart) only for the public API of a feature.

3. Enforcement (Check)

1. Review: Check if a new file is being created in the root or a 'dump' folder.
2. Block: "Stop. This belongs in features/<name>. Do not put logic in pages/."

Framework Standards

A. Next.js (App Router)

• app/: Routing layer ONLY. (page.tsx, layout.tsx, route.ts). NO LOGIC.
  • app/(auth)/​login/​page.tsx -> Imports from @/​features/​auth
• features/: The brain.
  • features/​auth/​components/​LoginForm.tsx
  • features/​auth/​hooks/​useLogin.ts
  • features/​auth/​actions/​login.ts (Server Actions)
• components/: Shared dumb UI.
  • components/​ui/​button.tsx (Shadcn)
  • components/​layout/​header.tsx
• lib/: Singletons (Prisma, Stripe, Redis clients).

B. Flutter (Clean + Riverpod)

• lib/​main.dart: Entry point.
• lib/​core/: Routing, Themes, Constants, Extensions.
• lib/​features/:
  • features/​auth/​presentation/​screens/
  • features/​auth/​presentation/​widgets/
  • features/​auth/​data/​repositories/
  • features/​auth/​domain/​models/
• lib/​shared/: Widgets used across multiple features.

C. Python (FastAPI / General)

• app/​main.py: App init.
• app/​core/: Config, Security, DB session.
• app/​routers/: V1 endpoints.
• app/​internal/: Admin routes.
• app/​services/ (Optional): If logic is heavy.
• Note: Python often prefers flat structures initially. Group by "Domain" (e.g., app/​users/, app/​items/) if the app grows.

Best Practices (Recommended)

1. Filenames:
   • JS/​TS: camelCase for variables/​functions, PascalCase for Components/​Classes, kebab-case for folders/​routes.
   • Dart: always snake_case for filenames.
   • Python: always snake_case.
2. Barrel Files: Avoid them for internal usage (causes circular deps). Use them ONLY to expose a Feature's public API to the rest of the app:
   • Right: import { LoginForm } from '@/​features/​auth' (where features/​auth/​index.ts exists).
   • Wrong: import { Button } from '@/​components' (import directly: @/​components/​Button).

Self-Correction Checklist

Before creating a file, ask:

1. "Is this file specific to one feature (e.g., 'Delete Task Button')?" -> Put in features/​tasks/​components.
2. "Is this file generic (e.g., 'Red Delete Button')?" -> Put in components/​ui.
3. "Is this file a page?" -> Put in app/ (Next.js) or screens/ (Flutter), but keep it empty (logic goes to feature).