stylemate-architecture

# StyleMate Architecture Plugin

Comprehensive Claude Code plugin for building production-ready microservices in the StyleMate platform. Provides specialized agents, reusable skills, and automation commands for React microfrontends with Module Federation and .NET APIs with Clean Architecture.

## Features

### 🤖 Specialized Agents

#### work-planner-agent
Decomposes business requirements into executable plans across frontend, backend, and infrastructure layers.

**Use for**:
- Planning new microservices
- Breaking down features into tasks
- Creating architectural blueprints
- Defining security and QA requirements

**Capabilities**:
- Epic decomposition with "THINK HARDER" methodology
- Task generation for UI, API, Shell, and Infrastructure
- Security and authorization planning
- Docker and Nginx configuration
- Definition of Done (DoD) creation

**Example**:
```
Use the work-planner-agent to plan a staff scheduling system where employees
can view their schedules, set availability, and request time off.
```

#### ui-engineer-agent
Builds React 19 microfrontends with Module Federation, Material-UI, and JWT authentication.

**Use for**:
- Creating React components following atomic design
- Setting up Module Federation
- Implementing responsive mobile-first designs
- Integrating JWT authentication in frontends
- Building route configurations with authorization

**Capabilities**:
- Atomic design component creation (atoms → molecules → organisms → pages)
- Module Federation configuration
- MUI theme integration
- JWT Axios interceptor setup
- Route guard implementation
- Mobile-responsive layouts

**Example**:
```
Use the ui-engineer-agent to build the scheduling calendar page with week/month
views, shift creation, and employee filtering. It should work on mobile and desktop.
```

#### dotnet-engineer-agent
Creates ASP.NET Core 8 microservices with Clean Architecture, EF Core, and JWT.

**Use for**:
- Building .NET 8 APIs
- Implementing Clean Architecture
- Setting up EF Core with PostgreSQL
- Configuring JWT authentication and authorization
- Creating repository and service layers

**Capabilities**:
- Clean Architecture project structure (Domain/Application/Infrastructure/Controllers)
- JWT authentication with role-based policies
- EF Core configuration and migrations
- Business data isolation via JWT claims
- Health check implementation
- Docker containerization

**Example**:
```
Use the dotnet-engineer-agent to create the staff scheduling API with endpoints
for CRUD operations on schedules, shifts, and time-off requests.
```

### 🎯 Agent Skills

Skills are automatically invoked by Claude based on task context. You don't need to explicitly call them.

#### module-federation-setup
Sets up Vite Module Federation for React microfrontends.

**Automatically activates when**:
- Creating new microfrontend projects
- Configuring federation.config.ts
- Setting up shared dependencies
- Exposing routes to shell application

**Provides**:
- Complete federation.config.ts with proper shared dependencies
- Vite configuration with proxy settings
- Route export setup with metadata
- Shell integration instructions

#### clean-architecture-validator
Validates .NET API projects follow Clean Architecture principles.

**Automatically activates when**:
- Reviewing .NET project structure
- Checking for architectural violations
- Validating layer dependencies
- Ensuring proper separation of concerns

**Validates**:
- Domain layer has no dependencies
- Application depends only on Domain
- Infrastructure implements interfaces
- Controllers orchestrate workflows
- No circular dependencies

#### jwt-integration
Implements JWT authentication for both .NET and React.

**Automatically activates when**:
- Setting up authentication
- Configuring authorization policies
- Implementing token interceptors
- Adding route guards

**Provides**:
- .NET JWT validation configuration
- Authorization policy definitions
- React Axios interceptor setup
- Token refresh logic
- Route guard implementation

### ⚡ Slash Commands

#### /new-microservice
Scaffolds a complete new microservice with all required components.

**Creates**:
- .NET API with Clean Architecture
- React UI with Module Federation
- Docker configurations
- Nginx routing
- JWT authentication setup
- Database migrations

**Prompts for**:
- Context name
- API and UI ports
- Domain entities
- User roles

**Example**:
```
/new-microservice

Context: scheduling
API Port: 8003
UI Port: 3003
Entities: Schedule, Shift, TimeOff
Roles: Owner, Admin, Manager, Staff
```

#### /validate-architecture
Performs comprehensive architectural validation of a microservice.

**Checks**:
- Clean Architecture compliance
- JWT authentication setup
- Module Federation configuration
- Docker and health checks
- Business data isolation
- Security headers
- Integration with shell

**Generates**:
- Detailed validation report
- Pass/fail/warning status for each check
- Specific line numbers for issues
- Recommended fixes

**Example**:
```
/validate-architecture scheduling

# Optional: Auto-fix common issues
/validate-architecture scheduling --fix
```

## Installation

### From StyleMate Project
```bash
# Start Claude Code
claude

# Add marketplace
/plugin marketplace add ./market-plugin

# Install plugin
/plugin install stylemate-architecture@stylemate-plugins
```

### Verify Installation
```bash
# Check agents
/agents

# Should show:
# - work-planner-agent
# - ui-engineer-agent
# - dotnet-engineer-agent

# Check commands
/help

# Should show:
# - /new-microservice
# - /validate-architecture
```

## Usage Examples

### Example 1: Plan and Build New Feature

```
Step 1: Plan the feature
--------
Use the work-planner-agent to plan a feature where managers can create and assign
shifts to employees. Employees should see their assigned shifts in a calendar view.

Step 2: Build the API
--------
Use the dotnet-engineer-agent to implement the Shift entity and CRUD endpoints.
Only Managers and Admins should be able to create/edit shifts.

Step 3: Build the UI
--------
Use the ui-engineer-agent to create the shift calendar component with week and
month views. It should be responsive for mobile and desktop.

Step 4: Validate
--------
/validate-architecture scheduling
```

### Example 2: Scaffold New Microservice

```bash
# Create complete microservice structure
/new-microservice

# Follow prompts to configure:
# - Context name: inventory
# - Entities: Product, Category, Supplier
# - Roles: Owner, Admin, Manager
# - Ports: API 8004, UI 3004

# Result: Complete microservice ready for development
```

### Example 3: Validate Existing Service

```bash
# Run comprehensive validation
/validate-architecture staff

# Review report:
# ✓ Clean Architecture: Passed
# ✗ JWT Authorization: Failed (missing [Authorize] on line 42)
# ⚠ Module Federation: Warning (update react-router-dom to singleton)
# ✓ Docker: Passed

# Apply auto-fixes
/validate-architecture staff --fix
```

## Architecture Patterns Enforced

### Clean Architecture (.NET)
```
Domain/          # Business entities and interfaces (no dependencies)
Application/     # Business logic and DTOs (depends on Domain)
Infrastructure/  # Data access and external services (implements interfaces)
Controllers/     # API orchestration (depends on all layers)
```

### Atomic Design (React)
```
atoms/        # Basic UI elements (Button, Input, Label)
molecules/    # Simple composites (SearchBox, FormField)
organisms/    # Complex components (DataTable, Modal, Header)
pages/        # Complete pages (Dashboard, ScheduleView)
```

### Module Federation
```typescript
// Exposes routes for consumption by shell
exposes: {
  './routes': './src/app/routes.tsx'
}

// Shares dependencies as singletons
shared: {
  'react': { singleton: true },
  'react-dom': { singleton: true },
  '@mui/material': { singleton: true }
}
```

### JWT Authentication
```csharp
// .NET Authorization Policies
"RequireOwnerOrAdmin": roles = ["Owner", "Admin"]
"RequireManagerOrAbove": roles = ["Owner", "Admin", "Manager"]
"RequireStaffAccess": roles = ["Owner", "Admin", "Manager", "Staff"]
"RequireBusiness": claim = "business_id"
```

```typescript
// React Route Metadata
meta: {
  label: "Schedules",
  allowedRoles: ["Owner", "Admin", "Manager"],
  requireEmailConfirmed: true,
  requireBusiness: true
}
```

## Configuration

### Required Environment Variables
```env
# JWT Configuration
JWT_ISSUER=stylemate-auth
JWT_AUDIENCE=stylemate-services
JWT_SECRET_KEY=your-secret-key-here

# Database
POSTGRES_DB=stylemate
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres123

# Network
DOCKER_NETWORK=stylemate_net
```

### Nginx Routing Pattern
```nginx
# UI Remote
location /remotes/{context}-ui/ {
    proxy_pass http://{context}_ui:80/;
}

# API Endpoints
location /api/{context}/ {
    proxy_pass http://{context}_api:80/api/{context}/;
}
```

## Best Practices

### Agent Selection
- **Planning phase**: work-planner-agent
- **React development**: ui-engineer-agent
- **API development**: dotnet-engineer-agent

### Development Workflow
1. Plan with work-planner-agent
2. Build API with dotnet-engineer-agent
3. Build UI with ui-engineer-agent
4. Validate with /validate-architecture
5. Test with Docker Compose
6. Integrate with shell application

### Code Quality
- Always run `npm run lint` after UI changes
- Always run `dotnet build` after API changes
- Use Playwright testing for UI validation
- Write integration tests for APIs
- Validate architecture before deployment

## Troubleshooting

### Agent Not Available
```bash
# Check installation
/plugin

# Reinstall if needed
/plugin install stylemate-architecture@stylemate-plugins
```

### Skill Not Activating
Skills activate automatically. If you think a skill should have activated but didn't:
- Describe the task more explicitly
- Mention the specific technology (e.g., "Module Federation", "Clean Architecture")

### Command Not Found
```bash
# Verify commands are loaded
/help

# Restart Claude Code if needed
exit
claude
```

## Version History

### 1.0.0 (2025-01-19)
- Initial release
- 3 specialized agents (work-planner, ui-engineer, dotnet-engineer)
- 3 skills (module-federation-setup, clean-architecture-validator, jwt-integration)
- 2 commands (/new-microservice, /validate-architecture)

## License

MIT

## Support

For issues and questions:
- Review this documentation
- Check the main marketplace README
- Consult StyleMate platform documentation (CLAUDE.md)