SOLID React - Component Architecture

Codebase Analysis (MANDATORY)

Before ANY implementation:

• Explore project structure to understand architecture

• Read existing related files to follow established patterns

• Identify naming conventions, coding style, and patterns used

• Understand data flow and dependencies

DRY - Reuse or Create Shared (MANDATORY)

Before writing ANY new code:

• Grep the codebase for similar function names, patterns, or logic

• Check shared locations: modules/cores/lib/ , modules/cores/components/ , modules/cores/hooks/

• If similar code exists → extend/reuse instead of duplicate

• If code will be used by 2+ features → create it in modules/cores/ directly

• Extract repeated logic (3+ occurrences) into shared helpers

• Run npx jscpd ./src --threshold 3 after creating new files

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

• fuse-ai-pilot:explore-codebase - Analyze project structure and existing patterns

• fuse-ai-pilot:research-expert - Verify latest docs for all stack technologies

• mcp__context7__query-docs - Check integration compatibility

After implementation, run fuse-ai-pilot:sniper for validation.

Absolute Rules (MANDATORY)

1. Files < 100 lines

• Split at 90 lines - Never exceed 100

• Components < 50 lines (use composition)

• Hooks < 30 lines each

• Services < 40 lines each

2. Modular Architecture

See references/architecture-patterns.md for complete structure with feature modules and cores directory.

3. JSDoc Mandatory

/**

• Fetch user by ID from API.
• @param id - User unique identifier
• @returns User object or null if not found */ export async function getUserById(id: string): Promise<User | null>

4. Interfaces Separated

modules/[feature]/src/interfaces/ ├── user.interface.ts ├── post.interface.ts └── api.interface.ts

NEVER put interfaces in component files.

SOLID Principles (Detailed Guides)

Each SOLID principle has a dedicated reference guide:

references/single-responsibility.md

• One function = one reason to change

• File splitting at 90 lines (components < 50, hooks < 30)

• Component composition patterns

• Split strategy

references/open-closed.md

• Extend via composition, not modification

• Plugin architecture patterns

• Render props and slots

• Strategy patterns

references/liskov-substitution.md

• Contract compliance & behavioral subtyping

• Interface contracts

• Swappable implementations

• Testing compliance

references/interface-segregation.md

• Many focused interfaces beat one fat interface

• Role-based interfaces

• Props segregation

• Context splitting

references/dependency-inversion.md

• Depend on abstractions, not implementations

• Constructor injection patterns

• Factory patterns

• Context for DI

See references/solid-principles.md for overview and quick reference.

Code Templates

Ready-to-copy code in references/templates/ :

Template Usage Max Lines

component.md

React functional component 50

hook.md

Custom hook with TanStack Query 30

service.md

Service with dependency injection 40

store.md

Zustand store with persistence 40

interface.md

TypeScript interfaces

validator.md

Zod validation schemas 30

factory.md

Factory pattern 40

adapter.md

Adapter pattern 40

error.md

Custom error classes 30

test.md

Vitest + Testing Library

Response Guidelines

• Research first - MANDATORY: Search Context7 + Exa before ANY code

• Show complete code - Working examples, not snippets

• Explain decisions - Why this pattern over alternatives

• Include tests - Always suggest test cases

• Handle errors - Never ignore, use error boundaries

• Type everything - Full TypeScript, no any

• Document code - JSDoc for complex functions

Forbidden

• Coding without researching docs first (ALWAYS research)

• Using outdated APIs without checking current year docs

• Files > 100 lines

• Interfaces in component files

• Business logic in components

• Class components

• Missing JSDoc on exports

• any type

• Barrel exports (index.ts re-exports)

• useEffect for data fetching (use TanStack Query or Router loaders)

• Module importing another module (except cores)

• Duplicating existing utility/helper without Grep search first

• Copy-pasting logic blocks instead of extracting shared function