@girardmedia/bootspring 1.1.0

package/agents/architecture-expert/context.md

@@ -0,0 +1,454 @@
+# Architecture Expert Agent
+
+## Role
+Specialized in software architecture, system design, code organization, design patterns, and building scalable, maintainable applications.
+
+## Core Expertise
+
+### Next.js App Router Structure
+
+```
+app/
+├── (marketing)/           # Route group for marketing pages
+│   ├── page.tsx          # Landing page (/)
+│   ├── about/page.tsx    # /about
+│   └── pricing/page.tsx  # /pricing
+├── (dashboard)/          # Route group for authenticated area
+│   ├── layout.tsx        # Shared dashboard layout with sidebar
+│   ├── dashboard/page.tsx
+│   ├── settings/
+│   │   ├── page.tsx
+│   │   ├── profile/page.tsx
+│   │   └── billing/page.tsx
+│   └── projects/
+│       ├── page.tsx      # /projects
+│       └── [id]/
+│           ├── page.tsx  # /projects/[id]
+│           └── settings/page.tsx
+├── api/
+│   ├── webhooks/
+│   │   └── stripe/route.ts
+│   └── [...catchall]/route.ts  # API catch-all
+├── layout.tsx            # Root layout
+├── error.tsx            # Error boundary
+├── not-found.tsx        # 404 page
+└── loading.tsx          # Loading UI
+
+lib/
+├── db.ts                # Database client
+├── auth.ts              # Auth utilities
+├── utils.ts             # Shared utilities
+└── validations/         # Zod schemas
+    ├── user.ts
+    └── project.ts
+
+components/
+├── ui/                  # Base UI components (shadcn/ui style)
+│   ├── button.tsx
+│   ├── input.tsx
+│   └── card.tsx
+├── forms/               # Form components
+│   ├── login-form.tsx
+│   └── settings-form.tsx
+├── layouts/             # Layout components
+│   ├── header.tsx
+│   ├── sidebar.tsx
+│   └── footer.tsx
+└── features/            # Feature-specific components
+    ├── dashboard/
+    │   ├── stats-card.tsx
+    │   └── activity-feed.tsx
+    └── projects/
+        ├── project-card.tsx
+        └── project-list.tsx
+
+services/                # Business logic
+├── user-service.ts
+├── project-service.ts
+└── billing-service.ts
+
+types/                   # TypeScript types
+├── index.ts
+├── api.ts
+└── database.ts
+```
+
+### Feature-Based Architecture
+
+```
+features/
+├── auth/
+│   ├── components/
+│   │   ├── login-form.tsx
+│   │   ├── signup-form.tsx
+│   │   └── auth-provider.tsx
+│   ├── hooks/
+│   │   └── use-auth.ts
+│   ├── actions/
+│   │   └── auth-actions.ts
+│   ├── lib/
+│   │   └── auth-utils.ts
+│   └── types.ts
+├── billing/
+│   ├── components/
+│   │   ├── pricing-table.tsx
+│   │   ├── checkout-button.tsx
+│   │   └── subscription-card.tsx
+│   ├── hooks/
+│   │   └── use-subscription.ts
+│   ├── actions/
+│   │   └── billing-actions.ts
+│   └── types.ts
+└── projects/
+    ├── components/
+    ├── hooks/
+    ├── actions/
+    └── types.ts
+```
+
+### Service Layer Pattern
+
+```typescript
+// services/project-service.ts
+import { prisma } from '@/lib/db';
+import { CreateProjectInput, UpdateProjectInput } from '@/types';
+import { NotFoundError, UnauthorizedError } from '@/lib/errors';
+
+export class ProjectService {
+  async getAll(userId: string) {
+    return prisma.project.findMany({
+      where: {
+        OR: [
+          { ownerId: userId },
+          { members: { some: { userId } } },
+        ],
+      },
+      include: {
+        owner: { select: { id: true, name: true, avatar: true } },
+        _count: { select: { tasks: true, members: true } },
+      },
+      orderBy: { updatedAt: 'desc' },
+    });
+  }
+
+  async getById(id: string, userId: string) {
+    const project = await prisma.project.findUnique({
+      where: { id },
+      include: {
+        owner: true,
+        members: { include: { user: true } },
+        tasks: { orderBy: { createdAt: 'desc' }, take: 10 },
+      },
+    });
+
+    if (!project) {
+      throw new NotFoundError('Project');
+    }
+
+    const hasAccess = project.ownerId === userId ||
+      project.members.some(m => m.userId === userId);
+
+    if (!hasAccess) {
+      throw new UnauthorizedError('No access to this project');
+    }
+
+    return project;
+  }
+
+  async create(data: CreateProjectInput, userId: string) {
+    return prisma.project.create({
+      data: {
+        ...data,
+        ownerId: userId,
+        members: {
+          create: { userId, role: 'owner' },
+        },
+      },
+    });
+  }
+
+  async update(id: string, data: UpdateProjectInput, userId: string) {
+    const project = await this.getById(id, userId);
+
+    // Only owner can update
+    if (project.ownerId !== userId) {
+      throw new UnauthorizedError('Only the owner can update this project');
+    }
+
+    return prisma.project.update({
+      where: { id },
+      data,
+    });
+  }
+
+  async delete(id: string, userId: string) {
+    const project = await this.getById(id, userId);
+
+    if (project.ownerId !== userId) {
+      throw new UnauthorizedError('Only the owner can delete this project');
+    }
+
+    // Soft delete
+    return prisma.project.update({
+      where: { id },
+      data: { deletedAt: new Date() },
+    });
+  }
+}
+
+export const projectService = new ProjectService();
+```
+
+### Repository Pattern
+
+```typescript
+// repositories/base-repository.ts
+import { PrismaClient } from '@prisma/client';
+
+export abstract class BaseRepository<T> {
+  constructor(protected prisma: PrismaClient) {}
+
+  abstract findById(id: string): Promise<T | null>;
+  abstract findAll(): Promise<T[]>;
+  abstract create(data: Partial<T>): Promise<T>;
+  abstract update(id: string, data: Partial<T>): Promise<T>;
+  abstract delete(id: string): Promise<void>;
+}
+
+// repositories/user-repository.ts
+import { User, Prisma } from '@prisma/client';
+import { BaseRepository } from './base-repository';
+
+export class UserRepository extends BaseRepository<User> {
+  async findById(id: string) {
+    return this.prisma.user.findUnique({ where: { id } });
+  }
+
+  async findByEmail(email: string) {
+    return this.prisma.user.findUnique({ where: { email } });
+  }
+
+  async findAll() {
+    return this.prisma.user.findMany({
+      where: { deletedAt: null },
+      orderBy: { createdAt: 'desc' },
+    });
+  }
+
+  async create(data: Prisma.UserCreateInput) {
+    return this.prisma.user.create({ data });
+  }
+
+  async update(id: string, data: Prisma.UserUpdateInput) {
+    return this.prisma.user.update({ where: { id }, data });
+  }
+
+  async delete(id: string) {
+    await this.prisma.user.update({
+      where: { id },
+      data: { deletedAt: new Date() },
+    });
+  }
+}
+```
+
+### Dependency Injection
+
+```typescript
+// lib/container.ts
+import { PrismaClient } from '@prisma/client';
+import { UserRepository } from '@/repositories/user-repository';
+import { ProjectRepository } from '@/repositories/project-repository';
+import { UserService } from '@/services/user-service';
+import { ProjectService } from '@/services/project-service';
+
+class Container {
+  private static instance: Container;
+  private _prisma: PrismaClient;
+  private _userRepository: UserRepository;
+  private _projectRepository: ProjectRepository;
+  private _userService: UserService;
+  private _projectService: ProjectService;
+
+  private constructor() {
+    this._prisma = new PrismaClient();
+    this._userRepository = new UserRepository(this._prisma);
+    this._projectRepository = new ProjectRepository(this._prisma);
+    this._userService = new UserService(this._userRepository);
+    this._projectService = new ProjectService(this._projectRepository);
+  }
+
+  static getInstance() {
+    if (!Container.instance) {
+      Container.instance = new Container();
+    }
+    return Container.instance;
+  }
+
+  get userService() { return this._userService; }
+  get projectService() { return this._projectService; }
+}
+
+export const container = Container.getInstance();
+
+// Usage
+import { container } from '@/lib/container';
+
+async function handler() {
+  const projects = await container.projectService.getAll(userId);
+}
+```
+
+### Event-Driven Architecture
+
+```typescript
+// lib/events/emitter.ts
+type EventHandler<T = unknown> = (payload: T) => void | Promise<void>;
+
+class EventEmitter {
+  private handlers: Map<string, EventHandler[]> = new Map();
+
+  on<T>(event: string, handler: EventHandler<T>) {
+    const handlers = this.handlers.get(event) || [];
+    handlers.push(handler as EventHandler);
+    this.handlers.set(event, handlers);
+  }
+
+  async emit<T>(event: string, payload: T) {
+    const handlers = this.handlers.get(event) || [];
+    await Promise.all(handlers.map(handler => handler(payload)));
+  }
+}
+
+export const events = new EventEmitter();
+
+// Events definition
+// lib/events/types.ts
+export type Events = {
+  'user.created': { userId: string; email: string };
+  'user.updated': { userId: string; changes: string[] };
+  'project.created': { projectId: string; ownerId: string };
+  'subscription.started': { userId: string; plan: string };
+};
+
+// Event handlers
+// lib/events/handlers.ts
+import { events } from './emitter';
+import { sendWelcomeEmail } from '@/lib/email';
+import { trackEvent } from '@/lib/analytics';
+
+events.on('user.created', async ({ userId, email }) => {
+  await sendWelcomeEmail(userId, email);
+  await trackEvent('user_signup', { userId });
+});
+
+events.on('subscription.started', async ({ userId, plan }) => {
+  await trackEvent('subscription_started', { userId, plan });
+});
+
+// Usage in service
+async function createUser(data: CreateUserInput) {
+  const user = await prisma.user.create({ data });
+  await events.emit('user.created', { userId: user.id, email: user.email });
+  return user;
+}
+```
+
+### Clean Architecture Layers
+
+```
+┌─────────────────────────────────────────┐
+│           Presentation Layer            │
+│  (Components, Pages, API Routes)        │
+├─────────────────────────────────────────┤
+│           Application Layer             │
+│  (Use Cases, Services, Actions)         │
+├─────────────────────────────────────────┤
+│             Domain Layer                │
+│  (Entities, Value Objects, Events)      │
+├─────────────────────────────────────────┤
+│         Infrastructure Layer            │
+│  (Database, External APIs, Cache)       │
+└─────────────────────────────────────────┘
+
+Rules:
+- Inner layers don't depend on outer layers
+- Dependencies point inward
+- Domain layer has no external dependencies
+```
+
+### Error Handling Strategy
+
+```typescript
+// lib/errors.ts
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode: number = 400,
+    public isOperational: boolean = true
+  ) {
+    super(message);
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(public errors: Record<string, string[]>) {
+    super('Validation failed', 'VALIDATION_ERROR', 400);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string) {
+    super(`${resource} not found`, 'NOT_FOUND', 404);
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') {
+    super(message, 'UNAUTHORIZED', 401);
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = 'Forbidden') {
+    super(message, 'FORBIDDEN', 403);
+  }
+}
+
+// Global error handler
+export function handleError(error: unknown) {
+  if (error instanceof AppError && error.isOperational) {
+    return {
+      error: error.message,
+      code: error.code,
+      ...(error instanceof ValidationError && { details: error.errors }),
+    };
+  }
+
+  // Log unexpected errors
+  console.error('Unexpected error:', error);
+
+  return {
+    error: 'Internal server error',
+    code: 'INTERNAL_ERROR',
+  };
+}
+```
+
+## Architecture Checklist
+
+- [ ] Clear separation of concerns
+- [ ] Dependencies flow inward
+- [ ] Business logic in services/domain
+- [ ] Database access through repositories
+- [ ] Consistent error handling
+- [ ] Type safety throughout
+- [ ] Feature-based organization
+- [ ] Shared code in lib/
+- [ ] Environment configuration validated
+- [ ] Logging and monitoring in place
+
+## Trigger Keywords
+architecture, structure, pattern, design, organize, folder, layer, service, repository, dependency, clean, solid, scale, modular, feature, domain