┌─────────────────────────────────────────────────────────────────────┐
│                    MODULAR ARCHITECTURE                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  FRONTEND MODULES          MIDDLEWARE           BACKEND MODULES     │
│  (React/Next.js)           (API Layer)          (Python/Services)   │
│                                                                     │
│  ┌─────────────┐          ┌───────────┐        ┌─────────────────┐ │
│  │ UI Module   │ ───────▶ │ API Route │ ─────▶ │ Module 1:       │ │
│  │ (Component) │          │ (Contract)│        │ Ingestion       │ │
│  └─────────────┘          └───────────┘        ├─────────────────┤ │
│                                                │ Module 2:       │ │
│  ┌─────────────┐          ┌───────────┐        │ Graph Maint.    │ │
│  │ State       │ ◀─────── │ Response  │ ◀───── ├─────────────────┤ │
│  │ Management  │          │ Contract  │        │ Module 3:       │ │
│  └─────────────┘          └───────────┘        │ Output Engine   │ │
│                                                ├─────────────────┤ │
│  Interface contracts       Versioned APIs      │ Module 4:       │ │
│  between all layers        with schemas        │ AI Analysis     │ │
│                                                ├─────────────────┤ │
│                                                │ Module 5:       │ │
│                                                │ Human Decision  │ │
│                                                ├─────────────────┤ │
│                                                │ Module 6:       │ │
│                                                │ Trust & Audit   │ │
│                                                └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

BEFORE: "I added a button to the UI... now what does the backend need?"
        → Confusion about data flow, module boundaries, interface contracts

AFTER:  Describe feature → Get module mapping → Get interface contracts
        → Clear implementation path that respects modularity

Frontend: React + Vite
Backend: FastAPI (Python)
Database: Neo4j (graph) + SQLite (app state)
API: REST at /api/*
Auth: Clerk

Frontend: Next.js 16 (App Router)
Backend: API routes proxy to services
Database: Neo4j (via apex-helix) + Supabase
API: Next.js API routes → microservices
Auth: Supabase

// Interface Contract Template
interface ModuleContract {
  // Input schema (what the caller sends)
  request: {
    schema: "module.operation.v1";
    data: RequestType;
  };

  // Output schema (what the module returns)
  response: {
    success: boolean;
    data?: ResponseType;
    error?: { code: string; message: string };
    metadata: {
      module: string;
      operation: string;
      timestamp: string;
      audit_id?: string;  // If M6 involved
    };
  };
}

┌─────────────────┐     Contract A     ┌─────────────────┐
│  FRONTEND       │ ◀───────────────▶ │  MIDDLEWARE     │
│  (React)        │  - Request DTO     │  (API Routes)   │
│                 │  - Response DTO    │                 │
└─────────────────┘  - Error codes     └────────┬────────┘
                                                │
                                         Contract B
                                                │
                     ┌──────────────────────────┼──────────────────────────┐
                     │                          ▼                          │
              ┌──────┴──────┐           ┌──────────────┐           ┌───────┴─────┐
              │ Module 3    │           │ Module 4     │           │ Module 6    │
              │ Output      │◀─────────▶│ AI Analysis  │◀─────────▶│ Audit       │
              └─────────────┘ Contract C└──────────────┘ Contract D└─────────────┘

# Feature Spec: [Feature Name]

## User Story
As a [role], I want to [action] so that [benefit].

## Module Impact Analysis

| Module | Impact | Changes Required |
|--------|--------|------------------|
| M3: Output | Primary | New query endpoint |
| M5: Human Decision | Secondary | Approval workflow |
| M6: Audit | Required | Audit logging |

## Data Flow Diagram (Module-Aware)

---

## FRONTEND SPEC (Modular)

### Frontend Module Structure

Frontend components should be organized by domain, not by type:

### Component: [ComponentName]

**Module:** `src/modules/[domain]/components/[ComponentName].tsx`

**Exports:** Only via module index (encapsulation)
```typescript
// src/modules/obligations/index.ts
export { ObligationCard } from './components/ObligationCard';
export { useObligations } from './hooks/useObligations';
// Internal components NOT exported

interface [ComponentName]Props {
  // Props definition
}

// Local state
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
const [data, setData] = useState<DataType | null>(null);

// Use module-specific hook, not direct API call
import { useObligations } from '@/modules/obligations';

const { data, isLoading, error } = useObligations(id);

// Middleware responsibility: Route to module, NOT implement logic
export async function POST(request: Request) {
  // 1. Validate request against contract schema
  const body = await validateRequest(RequestSchema, request);

  // 2. Check auth/permissions
  const user = await requireAuth(request);

  // 3. Route to appropriate MODULE (not implement here)
  const result = await moduleRouter.dispatch({
    module: 'M3_OUTPUT',  // or M4_AI, M5_HUMAN, etc.
    operation: 'query_obligations',
    payload: body,
    context: { user, audit: true }
  });

  // 4. Return standardized response
  return Response.json(result);
}

# Each module exposes a standard interface
class OutputEngineModule:
    """
    Module 3: Output Engine
    Responsibility: Query processing, response building, guardrails
    """

    def handle(self, request: ModuleRequest) -> ModuleResponse:
        """
        Standard module entry point

        Input Contract:
          - operation: str (e.g., "query_obligations")
          - payload: dict (operation-specific)
          - context: dict (user, permissions, audit_id)

        Output Contract:
          - success: bool
          - data: dict (operation-specific)
          - metadata: dict (module, timestamp, etc.)
        """
        pass

@dataclass
class QueryObligationsRequest:
    filters: dict
    pagination: PaginationParams
    include_relationships: bool = False

@dataclass
class QueryObligationsResponse:
    obligations: List[Obligation]
    total_count: int
    page: int
    has_more: bool

M3: Output → M6: Audit (log query for compliance)
M3: Output → M4: AI (if semantic search requested)

(:NewNode {
  id: String,
  created_at: DateTime,
  // ...
})

(:ExistingNode)-[:NEW_RELATIONSHIP {
  // properties
}]->(:OtherNode)

// Query the frontend will need
MATCH (n:Node {id: $id})
RETURN n

-- If new table needed
CREATE TABLE feature_table (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  created_at TIMESTAMP DEFAULT NOW()
);

-- If column needed
ALTER TABLE existing_table ADD COLUMN new_column TYPE;

CONTEXT:
- Project: [apex-governance/apex-lens]
- Feature: [Feature name]
- Modules Touched: [M3: Output, M5: Human Decision, M6: Audit]

MODULARITY REQUIREMENTS:
- Each module is independent - changes in one don't break others
- All cross-module calls use interface contracts
- Frontend modules mirror backend module boundaries

TASK (in order):
1. BACKEND MODULE: Add operation to [Module Name] at [path]
   - Define input/output contracts
   - Implement module logic ONLY (not API)
   - Add cross-module calls if needed

2. MIDDLEWARE: Add API route at [path]
   - Validate request against contract
   - Route to module (don't implement logic here)
   - Return standardized response

3. FRONTEND MODULE: Add to src/modules/[domain]/
   - Create hook that calls API
   - Create component that uses hook
   - Export only public interface

4. INTEGRATION: Wire module to page/layout
   - Import from module index only
   - Don't import internal module files

CONSTRAINTS:
- Modules communicate ONLY via contracts
- No direct database calls from middleware
- No business logic in API routes
- Frontend imports via module index only
- All changes logged to M6: Audit

### 4. Apex-Specific Patterns

For apex-governance (Python FastAPI + React):

For apex-lens (Next.js + Services):

### 5. Example: Adding "Favourite Obligations" Feature (Module-Aware)

**User Request:** "I want users to be able to favourite obligations"

**Generated Spec:**

```markdown
# Feature Spec: Favourite Obligations

## User Story
As a trustee, I want to favourite obligations so that I can quickly access the ones most relevant to my scheme.

## Module Impact Analysis

| Module | Impact | Reason |
|--------|--------|--------|
| **M3: Output** | Primary | Query favourites, return with obligations |
| **M5: Human Decision** | None | No approval workflow needed |
| **M6: Audit** | Required | Log favourite actions for compliance |

**Modules NOT touched:**
- M1: Ingestion (not importing data)
- M2: Graph Maintenance (not modifying graph structure)
- M4: AI Analysis (no AI involved)

## Data Flow (Module-Aware)

---

## FRONTEND MODULE SPEC

### Module: `src/modules/favourites/`

**Public Exports (index.ts):**
```typescript
// ONLY export what other modules need
export { FavouriteButton } from './components/FavouriteButton';
export { useFavourites, useToggleFavourite } from './hooks/useFavourites';
export type { Favourite } from './api/favourites.api';

// Contract matches backend module interface
export interface ToggleFavouriteRequest {
  entity_type: 'obligation' | 'legislation' | 'definition';
  entity_id: string;
}

export interface ToggleFavouriteResponse {
  success: boolean;
  data: { favourited: boolean; favourite_id?: string };
  metadata: { module: 'M3_OUTPUT'; audit_id: string };
}

import { moduleRouter } from '@/lib/module-router';
import { ToggleFavouriteRequest } from '@/modules/favourites';

export async function POST(request: Request) {
  // 1. Validate against contract
  const body = await validateRequest(ToggleFavouriteRequest, request);

  // 2. Auth check
  const user = await requireAuth(request);

  // 3. Route to M3: Output (NOT implement here)
  const result = await moduleRouter.dispatch({
    module: 'M3_OUTPUT',
    operation: 'toggle_favourite',
    payload: body,
    context: { user_id: user.id, audit: true }
  });

  return Response.json(result);
}

# backend/modules/output_engine.py

class OutputEngineModule:

    def toggle_favourite(
        self,
        request: ToggleFavouriteRequest,
        context: RequestContext
    ) -> ToggleFavouriteResponse:
        """
        Module 3 operation: Toggle user favourite

        Cross-module calls:
        - M6: Audit → log the action
        """
        # 1. Check existing favourite
        existing = self.persistence.get_favourite(
            user_id=context.user_id,
            entity_type=request.entity_type,
            entity_id=request.entity_id
        )

        # 2. Toggle
        if existing:
            self.persistence.delete_favourite(existing.id)
            favourited = False
        else:
            fav = self.persistence.create_favourite(
                user_id=context.user_id,
                entity_type=request.entity_type,
                entity_id=request.entity_id
            )
            favourited = True

        # 3. Cross-module call to M6: Audit
        audit_id = self.audit_module.log_action(
            action='favourite_toggle',
            user_id=context.user_id,
            entity_type=request.entity_type,
            entity_id=request.entity_id,
            result=favourited
        )

        return ToggleFavouriteResponse(
            success=True,
            data={'favourited': favourited},
            metadata={'module': 'M3_OUTPUT', 'audit_id': audit_id}
        )

-- Favourites are user preferences, not graph data
CREATE TABLE IF NOT EXISTS favourites (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  entity_type TEXT NOT NULL,
  entity_id TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  UNIQUE(user_id, entity_type, entity_id)
);

CONTEXT:
- Project: apex-governance
- Feature: Favourite obligations
- Modules: M3 (Output), M6 (Audit)

ORDER OF IMPLEMENTATION:

1. BACKEND MODULE (M3: Output)
   - Add toggle_favourite operation to output_engine.py
   - Add cross-module call to M6 for audit logging
   - Define input/output dataclasses

2. DATABASE
   - Add favourites table to persistence.py
   - Add get_favourite, create_favourite, delete_favourite methods

3. MIDDLEWARE
   - Add POST /api/favourites route
   - Route to M3, don't implement logic

4. FRONTEND MODULE
   - Create src/modules/favourites/ directory
   - Add FavouriteButton component
   - Add useFavourites hook
   - Export via index.ts

5. INTEGRATION
   - Import FavouriteButton from '@/modules/favourites'
   - Add to ObligationCard

MODULARITY TEST:
- Feature should work if M4 (AI) module is unavailable
- Audit should log even if UI fails to update

## Model Preference

**opus** - Fullstack planning requires understanding entire system architecture

---
*Part of 45Black UI Expert Devstack*
*For non-coders: Describe what you want, get specs for frontend AND backend*