System Architecture

• Agents: All human and AI agents that interact with the system
• Information: Data entities and their relationships
• Context: Operating environment and integration points
• Subsystems: Logical boundaries already identified

From real.md, extract:

• Required constraints: Security, data handling, deployment requirements
• Optional constraints: Performance, compatibility preferences

System Architecture Design

Overview

This skill guides the design of system architecture for modern web applications. To create robust architecture, select appropriate patterns, decompose into subsystems, design APIs, establish directory structure, and document technical decisions.

💡 Affordance Perspective (Optional)

<details> <summary>Click to expand: Understanding architecture through affordances</summary>

Architecture isn't just code organization—it's the infrastructure that enables action possibilities for both human and AI agents. Good architecture makes actions perceivable (through clear APIs), executable (through well-defined interfaces), and feedback-rich (through structured responses).

While this skill uses traditional terminology (layers, subsystems, APIs), you can optionally think of:

• APIs as programmatic affordances for AI agents
• Components as visual affordances for humans
• State management as affordance availability tracking

See SKILL-affordance-theory.md for the complete affordance-based perspective.

</details>

When to Use This Skill

• Starting a new web application project
• Refactoring existing system architecture
• Designing API structure and endpoints
• Establishing project directory conventions
• Making and documenting technical decisions

Process

Phase 1: Select Architecture Pattern

Common Patterns for Web Apps:

Recommended for Next.js Apps:

Layered Architecture + Modular Design
├── Presentation Layer (React Components)
├── Application Layer (API Routes, Server Actions)
├── Domain Layer (Business Logic, Services)
└── Infrastructure Layer (Database, External APIs)

💡 Affordance Hint: Each layer exposes affordances to the layer above. APIs are affordances for the presentation layer; components are affordances for users.

Phase 2: Decompose into Subsystems

Identify bounded contexts and create subsystems.

Subsystem Template:

## Subsystem: [Name]

**Responsibility:** [Single sentence description]

**Components:**
- Component 1: [Description]
- Component 2: [Description]

**Interfaces:**
- Input: [What it receives]
- Output: [What it produces]

**Dependencies:**
- Depends on: [Other subsystems]
- Used by: [Dependent subsystems]

Standard Subsystems for Chat App:

Phase 3: Design API Structure

RESTful API Design Principles:

💡 Affordance Hint: When designing APIs, ask "What action does this endpoint afford?" Instead of just CRUD operations, think about the actual capabilities each endpoint provides to agents (human developers or AI assistants).

API Endpoint Template:

### [METHOD] /api/[resource]

**Description:** [What this endpoint does]

**Authentication:** Required/Optional/None

**Request:**
- Headers: [Required headers]
- Params: [URL parameters]
- Query: [Query parameters]
- Body: [Request body schema]

**Response:**
- 200: [Success response]
- 400: [Bad request]
- 401: [Unauthorized]
- 404: [Not found]
- 500: [Server error]

Standard API Structure:

/api
├── /auth
│   ├── POST /register     # User registration
│   ├── POST /login        # User login
│   ├── POST /logout       # User logout
│   └── GET  /session      # Get current session
├── /conversations
│   ├── GET  /             # List conversations
│   ├── POST /             # Create conversation
│   ├── GET  /:id          # Get conversation
│   ├── PUT  /:id          # Update conversation
│   ├── DELETE /:id        # Delete conversation
│   └── POST /:id/messages # Send message
├── /config
│   ├── GET  /api          # List API configs
│   ├── POST /api          # Add API config
│   └── ... 
└── /admin
    ├── GET  /stats        # System statistics
    ├── GET  /users        # User list
    └── ...

Phase 4: Establish Directory Structure

Next.js App Router Structure:

src/
├── app/                      # Next.js App Router
│   ├── (auth)/               # Auth route group
│   │   ├── login/
│   │   └── register/
│   ├── (main)/               # Main app route group
│   │   ├── chat/
│   │   │   └── [id]/
│   │   └── settings/
│   ├── admin/                # Admin routes
│   ├── api/                  # API routes
│   │   ├── auth/
│   │   ├── conversations/
│   │   └── ...
│   ├── layout.tsx
│   └── page.tsx
├── components/               # React components
│   ├── ui/                   # Base UI components
│   ├── chat/                 # Feature components
│   └── layout/               # Layout components
├── lib/                      # Utilities and config
│   ├── db/                   # Database
│   │   ├── schema.ts
│   │   └── index.ts
│   ├── auth/                 # Auth utilities
│   └── utils.ts
├── services/                 # Business logic
│   ├── auth.service.ts
│   ├── chat.service.ts
│   └── ...
├── hooks/                    # React hooks
├── types/                    # TypeScript types
└── constants/                # Constants

Directory Guidelines:

💡 Affordance Hint: Organize code by the affordances it enables, not just by technical type. For example, services/chat.service.ts contains the logic that enables all chat-related affordances (create, send, view).

Phase 5: Design Security Architecture

Security Layers:

┌─────────────────────────────────────┐
│         Transport Layer             │
│         (HTTPS, HSTS)               │
├─────────────────────────────────────┤
│         Authentication              │
│     (JWT/Session, Password Hash)    │
├─────────────────────────────────────┤
│         Authorization               │
│     (RBAC, Resource Ownership)      │
├─────────────────────────────────────┤
│         Data Protection             │
│   (Encryption, Input Validation)    │
└─────────────────────────────────────┘

Security Requirements Matrix:

Phase 6: Document Technical Decisions

Architecture Decision Record (ADR) Template:

## ADR-[XXX]: [Title]

**Status:** Proposed/Accepted/Deprecated

**Context:**
[What is the issue that we're seeing that is motivating this decision?]

**Decision:**
[What is the change that we're proposing and/or doing?]

**Consequences:**
[What becomes easier or more difficult to do because of this change?]

Example ADRs:

Output Template

# System Architecture Document

## 1. Architecture Overview
- Pattern: [Selected pattern]
- Deployment: [Deployment strategy]

## 2. System Diagram
[ASCII or image diagram]

## 3. Subsystems
### 3.1 [Subsystem 1]
### 3.2 [Subsystem 2]
...

## 4. API Design
### 4.1 Authentication APIs
### 4.2 Core APIs
...

## 5. Directory Structure
[Project structure]

## 6. Security Architecture
[Security layers and measures]

## 7. Technical Decisions
### ADR-001: [Title]
...

Quality Checklist

• Architecture pattern is appropriate for requirements
• All subsystems have clear responsibilities
• APIs follow RESTful conventions
• Directory structure supports modularity
• Security requirements are addressed
• Technical decisions are documented
• Constraints from real.md are incorporated

Integration with Other Skills

Additional Resources

• SKILL-affordance-theory.md: Complete affordance-based architecture perspective (theoretical)
• MAS-concept.md: Understanding architecture through Minimum Affordance Stories

Last Updated: 2025-12-05
Document Version: v3.1 (Practical with Affordance Hints)
Maintainer: 42COG Team