Architecting Structure

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