ToldoConjunto/skills/toldo-architecture-solid/SKILL.md

Agent Skill: toldo-architecture-solid

Metadata

name: toldo-architecture-solid
description: Guía para mantener arquitectura limpia con SOLID, separación lógica/presentación, componentes pequeños/reutilizables y DI. Aplicar estrictamente en este proyecto.

When to use

Use this skill when:

• Creating new packages/modules
• Designing components or services
• Reviewing code for architectural violations
• Refactoring to improve structure
• Deciding where code should live

Architecture Layers

Layer Responsibilities

Layer	Location	Responsibility	Can Import	Cannot Import
Domain	packages/core/	Entities, value objects, business rules, repository interfaces	Nothing (pure TS)	data, services, ui, apps, @capacitor/*, frameworks
Infrastructure/Data	packages/data/	Repository implementations, DB schema/migrations, external adapters	core/	services, ui, apps, @capacitor/* in business logic
Application/Services	packages/services/	Use cases, orchestration, application logic	core/, data/	ui, apps (business logic), @capacitor/* directly
Presentation/UI	packages/ui/	Reusable UI components, design system	core/, services/ via interfaces	data/ directly, @capacitor/* directly
App/Composition	apps/toldo-app/	Composition root, routing, DI setup, Capacitor integration	All packages	- (can import anything, but keep orchestration here)

SOLID Checklist

Single Responsibility Principle (SRP)

• Each class/function does one thing
• Components have single purpose
• Services handle one domain area or specific use case
• Files are focused (< ~200 lines ideally, < 150 for components)

Open/Closed Principle (OCP)

• Use interfaces for extensibility
• Prefer composition over inheritance
• New features via new classes/functions, not modifying existing tested code

Liskov Substitution Principle (LSP)

• Implementations are substitutable for interfaces
• No breaking contracts

Interface Segregation Principle (ISP)

• Small, focused interfaces
• Repositories have specific methods, not "god" interfaces
• Clients don't depend on unused methods

Dependency Inversion Principle (DIP)

• Core defines interfaces (ports)
• Data/services implement/adapt (adapters)
• Depend on abstractions, inject dependencies
• No new of concrete implementations deep in business logic

Component Guidelines

Component Rules

• Small and focused: One responsibility per component
• Presentation-first: Minimal logic, delegate to composables/services
• Props down, events up: Clear data flow
• Reusable: Generic where possible, specific where needed
• No business rules: Calculations/validations belong in core/services
• No direct DB access: Use services through DI/composition
• No direct Capacitor imports: Go through adapters/services

Composables/Hooks

• Extract reusable logic to composables/hooks
• Keep UI concerns separate from business logic
• Make testable in isolation

Anti-Patterns to Avoid

• ❌ Importing Dexie directly in UI components
• ❌ Importing @capacitor/* in core/services/ui packages
• ❌ Business logic in Vue/React/Svelte components
• ❌ God classes/components doing too much
• ❌ Circular dependencies
• ❌ any types
• ❌ Tight coupling to frameworks in domain

Review Checklist

Before committing:

• Dependencies follow layer rules
• Component < ~150 lines
• No business logic in presentation
• Uses interfaces, not concrete classes
• Tested appropriately
• TypeScript strict compliant
• Follows naming conventions
• No circular deps

Resources

• See openspec/changes/add-toldo-poc-capacitor/design.md for full architecture
• Follow dependency rules strictly
• When in doubt, put logic in core/ or services/, keep UI dumb