---
name: valec3/frontend-architecture-screaming
source: https://app.decimal.ai/s/valec3-frontend-architecture-screaming@1/SKILL.md
source_sha256: 341a2548799c
---

# Frontend Architecture Screaming

## When to use this skill
- Business logic should be obvious from folder structure
- Onboarding new developers quickly
- Domain-first (not tech-first) organization
- Clear separation between business and technical concerns

## Workflow
- [ ] Organize by **what** the app does (not how)
- [ ] Name folders after business concepts
- [ ] Technical details (React, API) are secondary
- [ ] Make architecture decisions visible

## Instructions

### Screaming vs Generic Structure

**❌ Generic (Tech-First)**
```
src/
├── components/
├── hooks/
├── services/
└── utils/
```
*Problem: Doesn't tell you what the app does*

**✅ Screaming (Domain-First)**
```
src/
├── OrderManagement/
│   ├── OrderApproval/
│   ├── OrderTracking/
│   └── OrderHistory/
├── InventoryControl/
│   ├── StockManagement/
│   └── SupplierOrders/
├── CustomerSupport/
│   ├── TicketSystem/
│   └── LiveChat/
└── _infrastructure/    # Technical plumbing
```

### Key Principles

**1. Business Concepts First**
```
features/
├── ProductCatalog/
│   ├── ProductSearch/
│   │   ├── SearchBar.tsx
│   │   ├── SearchResults.tsx
│   │   └── useProductSearch.ts
│   ├── ProductDetails/
│   └── ProductReviews/
```

**2. Technical Folders are Hidden**
Prefix with `_` to de-emphasize:
```
_infrastructure/
├── _api/
├── _routing/
└── _state/
```

**3. Naming Convention**
- Use **business terms** from domain experts
- Avoid generic names like "Manager", "Handler"
- Be explicit: `OrderApprovalWorkflow` not `Workflow`

**4. Example Structure**
```
src/
├── Appointment Scheduling/
│   ├── BookAppointment/
│   ├── CancelAppointment/
│   └── RescheduleAppointment/
├── Patient Records/
│   ├── MedicalHistory/
│   ├── TestResults/
│   └── Prescriptions/
├── Billing/
│   ├── GenerateInvoice/
│   ├── ProcessPayment/
│   └── InsuranceClaims/
└── _infrastructure/
    ├── _api/
    ├── _components/  # Generic UI
    └── _utils/
```

## Resources
- Business value is immediately visible
- Technical implementation is secondary
- Folder structure = table of contents for business