@sprouted/create-vibes/templates/base/docs/architecture-visual.md

Create a new Vibes monorepo

# Vibes Architecture - Visual Guide

## The Big Picture

```
┌─────────────────────────────────────────────────────┐
│                    🌊 VIBES                          │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Apps (Containers)          Features (Slices)       │
│  ┌──────────────┐          ┌───────────────┐       │
│  │   📱 Mobile  │          │  📝 Todo      │       │
│  │              │  ──────► │  ┝━━━━━━━━━━━┥       │
│  │  TodoScreen  │          │  │ UI        │       │
│  └──────────────┘          │  │ API       │       │
│                            │  │ Logic     │       │
│  ┌──────────────┐          │  │ Data      │       │
│  │   🌐 Web     │          │  └───────────┘       │
│  │              │  ──────►                         │
│  │  Dashboard   │          ┌───────────────┐       │
│  └──────────────┘          │  👤 User      │       │
│                            │  ┝━━━━━━━━━━━┥       │
│  ┌──────────────┐          │  │ UI        │       │
│  │   ⚡ API     │  ──────► │  │ API       │       │
│  │              │          │  │ Logic     │       │
│  │   Routes     │          │  │ Data      │       │
│  └──────────────┘          └───────────┘       │
│                                                     │
└─────────────────────────────────────────────────────┘
```

## Feature Anatomy

```
feature-name/
│
├── 🎨 ui/              (Presentation Layer)
│   ├── components/     - Reusable UI pieces
│   └── screens/        - Full page views
│
├── 🔌 api/             (HTTP Layer)
│   ├── routes/         - URL endpoints
│   └── handlers/       - Request handlers
│
├── 🧠 logic/           (Business Layer)
│   ├── services/       - Business rules
│   └── validators/     - Data validation
│
├── 💾 data/            (Persistence Layer)
│   ├── models/         - Data structures
│   └── repositories/   - Data access
│
└── 🧪 tests/           (Quality Layer)
    ├── unit/          - Isolated tests
    └── integration/   - Full flow tests
```

## Data Flow

```
User Action
    │
    ▼
┌──────────┐
│   App    │ (Orchestrator)
└─────┬────┘
      │
      ▼
┌──────────┐
│ Feature  │ (Self-contained slice)
├──────────┤
│   UI     │ ◄─── Display
├──────────┤      │
│  Logic   │ ◄─── Process
├──────────┤      │
│   Data   │ ◄─── Store
└──────────┘
```

## Import Rules

```
✅ Allowed:
- App imports from Features
- Feature imports from Shared
- Any layer within same Feature

❌ Not Allowed:
- Feature imports from App
- Feature imports from Feature
- Cross-feature dependencies

Example:
app/web/main.ts
  └─► @features/todo
  └─► @features/user
  └─► @shared/ui

features/todo/index.ts
  └─► ./ui/TodoList
  └─► ./logic/TodoService
  └─► @shared/utils    ✓
  ❌  @features/user   ✗
```

## Quick Patterns

### Creating a Feature
```bash
features/
└── my-feature/
    ├── ui/          # "How it looks"
    ├── api/         # "How it's accessed"
    ├── logic/       # "How it works"
    └── data/        # "How it's stored"
```

### Using a Feature
```typescript
// Import what you need
import { 
  MyComponent,      // UI
  myRoutes,        // API
  MyService        // Logic
} from '@features/my-feature';

// Compose in your app
app.use(myRoutes);
app.render(<MyComponent />);
```

### Sharing Code
```typescript
// Put in shared/ only if:
// 1. Used by multiple features
// 2. Genuinely generic
// 3. Stable and tested

// Otherwise, duplicate first!
```

## Mental Model

Think of Vibes like a music festival:

- **Apps** = Different stages (Main Stage, Acoustic Tent, DJ Booth)
- **Features** = Different acts (complete performances)
- **Shared** = Common infrastructure (sound system, lights)

Each act (feature) brings everything they need. Stages (apps) just provide the space and coordinate the show!