Architecture patterns
for AI-assisted repositories

Group files by feature instead of technical role.

• - avoid duplicated hooks
• - preserve feature boundaries
• - keep business logic isolated

oversized shared utility folders

Old dashboard modules still depend on legacy validation patterns.

Prefer server components unless interactivity is required.

• - fetch on server
• - avoid client waterfalls
• - preserve async boundaries

mixed client/server logic

Old dashboard modules still depend on legacy validation patterns.

Centralize reusable validation schemas.

• - reuse schemas
• - avoid inline validation
• - preserve typing consistency

duplicated zod validators

Old dashboard modules still depend on legacy validation patterns.

Move all data fetching to the server layer.

• - fetch on server
• - avoid client hydration overhead
• - stream when possible

mixed server and client fetching patterns

Old dashboard modules still depend on legacy validation patterns.

Keep all reusable UI in /components/ui. Business UI in features.

• - reuse primitives
• - avoid inline styles
• - keep spacing consistent

inconsistent UI patterns across different features

Old dashboard modules still depend on legacy validation patterns.

Keep PRs isolated and incremental.

• - under 300 LOC
• - single responsibility
• - preserve architecture consistency

mixed feature concerns inside one PR

Old dashboard modules still depend on legacy validation patterns.

Require loading, error, empty and accessibility checks on every generated feature.

• - test behavior not implementation
• - avoid excessive mocking
• - prefer integration tests

tests passing but production flows broken

Old dashboard modules still depend on legacy validation patterns.

Keep package boundaries explicit.

• - avoid circular imports
• - isolate shared packages
• - preserve dependency direction

shared UI package importing business logic

Old dashboard modules still depend on legacy validation patterns.

Document legacy areas explicitly so AI avoids adding to them.

• - prevent AI from adding to legacy code
• - document deprecated patterns
• - maintain migration timeline

new features built on deprecated patterns

Old dashboard modules still depend on legacy validation patterns.