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).