# Feature Showcase Template

Generic template for creating feature showcases with Docker orchestration, mock API, and external store patterns.

## Quick Start

### 1. Copy Template

```bash
cp -r codebase/@templates/feature-showcase codebase/features/my-feature/frontend-showcase
cd codebase/features/my-feature/frontend-showcase
```

### 2. Configure Environment

```bash
cp .env.example .env
```

Edit `.env` and customize:

```env
FEATURE_NAME=my-feature          # Used in Docker container names
VITE_PORT=5200                   # Frontend dev server port (must be unique)
BACKEND_PORT=3015                # Backend API port (for proxy)
DB_PORT=25432                    # PostgreSQL port (must be unique)
BACKEND_PATH=../../backend-api   # Relative path to backend service
PROXY_TARGETS='["/api/my-feature"]'  # API routes to proxy
```

### 3. Install Dependencies

```bash
bun install
```

### 4. Start Showcase

```bash
bun run showcase
```

This starts:
1. PostgreSQL (port from `.env`)
2. Backend API (if `BACKEND_PATH` configured)
3. Vite dev server (port from `.env`)

Open `http://localhost:${VITE_PORT}` to view the showcase.

## Customization

### Mock API Routes

Edit `src/mock-routes.ts` to add feature-specific API handlers:

```typescript
export const mockRoutes: MockRoute[] = [
  {
    pattern: '/api/my-feature/items',
    handler: async (url, init) => {
      const items = store.getSnapshot().items;
      return jsonResponse(items);
    },
  },
];
```

### Store Domain Methods

Edit `src/store-instance.ts` to add feature-specific methods:

```typescript
export const store = createShowcaseStore<MyItem>({
  initialItems: SEED_DATA,
  domainMethods: {
    publishItem: (id: string) => {
      return store.updateItem(id, { status: 'published' });
    },
    // More domain methods...
  },
});
```

### Views

Edit `src/routes/` to implement feature-specific views:

- `BrowseView.tsx` - Master-detail layout for browsing items
- `ManageView.tsx` - CRUD operations for managing items
- Add more views as needed

Update `src/App.tsx` to register new routes.

### Seed Data

Edit `src/seed-data.ts` to provide initial data:

```typescript
export const SEED_DATA: MyItem[] = [
  { id: '1', name: 'Example', ... },
];
```

## Extension Points

### Adding a Service

To add a worker service:

1. Edit `package.json`:
   ```json
   {
     "scripts": {
       "showcase:worker": "cd ../../worker && bun run dev",
       "showcase:start": "concurrently --kill-others --names \"db,api,worker,ui\" -c \"blue,magenta,yellow,cyan\" \"bun run showcase:db\" \"bun run showcase:api\" \"bun run showcase:worker\" \"bun run showcase:ui\""
     }
   }
   ```

2. Add port to `.env`:
   ```env
   WORKER_PORT=3021
   ```

### External Service Dependency

To depend on another platform service (like Profile depends on Attributes):

1. Set `BACKEND_PATH` in `.env`:
   ```env
   BACKEND_PATH=../../attributes/backend-api
   ```

2. Add proxy targets:
   ```env
   PROXY_TARGETS='["/api/attributes/*", "/api/shared/*"]'
   ```

3. Import components from other features:
   ```env
   FEATURE_PACKAGE_IMPORT=@lilith/attributes-admin
   FEATURE_PACKAGE_PATH=../../attributes/frontend-admin/src
   ```

### Custom Vite Alias

To add a feature-specific alias (like `@/`):

```env
FEATURE_FRONTEND_PATH=../frontend-app/src
```

This enables:
```typescript
import { MyComponent } from '@/components/MyComponent';
```

## Architecture

### Orchestration

Uses `concurrently` to run services in parallel:

1. **db phase**: Docker Compose (PostgreSQL + Redis)
2. **api phase**: Backend services (waits for db)
3. **ui phase**: Vite dev server (waits for api)

Stop with: `bun run showcase:stop`

Clean database with: `bun run showcase:clean`

### State Management

Uses external store pattern with `useSyncExternalStore`:

- No React Context overhead
- Automatic cross-view synchronization
- Easy testing (no provider wrapper)

```typescript
// In component:
const { items } = useSyncExternalStore(
  store.subscribe,
  store.getSnapshot
);
```

### Mock API

Fetch interception with fallthrough:

- Mock feature-specific endpoints (CRUD operations)
- Proxy shared endpoints to real backend (via Vite proxy)

```typescript
setupMockAPI([
  { pattern: '/api/my-feature', handler: mockHandler },
]);
// Other requests → Vite proxy → real backend
```

### Vite Plugins

**lilithPackageResolver**: Resolves `@lilith/ui-*` from source or node_modules
- Priority 1: Root node_modules (workspace symlinks)
- Priority 2: Source packages (for HMR)

**bunStoreResolver**: Resolves transitive deps from `.bun/` store
- Version pinning for major versions (framer-motion@11, react-router-dom@7)
- Excludes Vite-managed packages (React, styled-components)

## Commands

- `bun run showcase` - Start all services
- `bun run showcase:stop` - Stop Docker services
- `bun run showcase:clean` - Stop and remove database (fresh start)
- `bun run showcase:db` - Start PostgreSQL only
- `bun run showcase:api` - Start backend API only
- `bun run showcase:ui` - Start frontend only
- `bun run build` - Build for production
- `bun run test` - Run vitest tests
- `bun run e2e` - Run Playwright E2E tests

## Troubleshooting

### Port Conflicts

Error: `Error: listen EADDRINUSE: address already in use :::5200`

**Solution**: Change `VITE_PORT` in `.env` to an unused port

### Package Resolution Errors

Error: `Failed to resolve import "@lilith/ui-layout"`

**Solution**:
1. Check `UI_PACKAGES_ROOT` in `.env` points to correct path
2. Verify package exists in root `node_modules` or source packages
3. Check Vite console for resolution attempts

### Proxy Not Working

Error: `GET /api/my-feature 404`

**Solution**:
1. Verify backend API is running (`bun run showcase:api`)
2. Check `PROXY_TARGETS` includes the path in `.env`
3. Check `BACKEND_PORT` matches backend's actual port
4. Check Vite proxy config in browser network tab

### Docker Services Won't Start

Error: `Cannot connect to Docker daemon`

**Solution**:
1. Ensure Docker Desktop is running
2. Check Docker service: `docker ps`
3. Try restarting Docker

## Reference Implementations

See these showcases for examples:

- **Profile**: `features/profile/frontend-showcase/` — Complex (3 services, external deps)
- **Quality Assurance**: `features/quality-assurance/frontend-showcase/` — Simple (UI only)

## Documentation

For more information:

- **Platform docs**: `docs/development/feature-showcase-template.md`
- **Vite config**: See `vite.config.ts` comments
- **Store pattern**: See `src/store.ts` comments
- **Mock API**: See `src/mock-api.ts` comments