Technical Analysis

Technical Analysis Skill

Overview

This skill provides techniques for analyzing technical aspects of software systems including APIs, data models, integrations, and security requirements.

API Analysis

REST API Analysis

Endpoint Discovery

Look for these patterns:

• Route definitions
• Controller classes
• OpenAPI/Swagger specifications
• API documentation

Endpoint Documentation Template

### Endpoint: {METHOD} {PATH}

**Purpose**: {DESCRIPTION}

**Authentication**: {AUTH_METHOD}

**Request**:
- Headers: {HEADERS}
- Parameters: {PARAMS}
- Body: {BODY_SCHEMA}

**Response**:
- Success (200): {SUCCESS_SCHEMA}
- Error (4xx/5xx): {ERROR_SCHEMA}

**Business Rules**:
- {RULE_1}
- {RULE_2}

API Quality Checklist

• [ ] Consistent naming conventions
• [ ] Proper HTTP methods used
• [ ] Appropriate status codes
• [ ] Error responses standardized
• [ ] Pagination implemented for lists
• [ ] Versioning strategy in place
• [ ] Rate limiting configured
• [ ] Authentication documented

GraphQL API Analysis

Schema Analysis

type Query {
  user(id: ID!): User
  orders(userId: ID!, status: OrderStatus): [Order]
}

type Mutation {
  createOrder(input: CreateOrderInput!): Order
  updateOrderStatus(id: ID!, status: OrderStatus!): Order
}

Document

• Queries available (read operations)
• Mutations available (write operations)
• Types and their relationships
• Required vs optional fields
• Custom scalars
• Directives used

Message/Event APIs

Event Schema Documentation

### Event: {EVENT_NAME}

**Topic/Queue**: {TOPIC}
**Producer**: {PRODUCER_SERVICE}
**Consumers**: {CONSUMER_LIST}

**Payload Schema**:
{JSON_SCHEMA}

**Business Trigger**: {WHEN_PUBLISHED}
**Expected Response**: {CONSUMER_BEHAVIOR}

Data Model Analysis

Entity Analysis

Entity Documentation Template

## Entity: {ENTITY_NAME}

### Description
{BUSINESS_DESCRIPTION}

### Attributes
| Name | Type | Required | Description | Constraints |
|------|------|----------|-------------|-------------|
| id | UUID | Yes | Primary key | Auto-generated |
| name | string | Yes | Display name | Max 100 chars |
| status | enum | Yes | Current state | Active, Inactive |

### Relationships
| Related Entity | Type | Description |
|---------------|------|-------------|
| Order | 1:N | Customer has many orders |
| Address | 1:1 | Customer has one address |

### Business Rules
- {RULE_1}
- {RULE_2}

### Indexes
| Index Name | Columns | Purpose |
|------------|---------|---------|
| idx_email | email | Unique lookup |

Data Flow Analysis

Data Flow Documentation

## Data Flow: {FLOW_NAME}

### Overview
{DESCRIPTION}

### Source
- System: {SOURCE_SYSTEM}
- Entity: {SOURCE_ENTITY}
- Trigger: {TRIGGER_EVENT}

### Transformations
1. {TRANSFORMATION_1}
2. {TRANSFORMATION_2}

### Destination
- System: {DEST_SYSTEM}
- Entity: {DEST_ENTITY}
- Action: {CREATE/UPDATE/DELETE}

### Error Handling
- {ERROR_SCENARIO}: {HANDLING}

### Diagram
[Source] → [Transform] → [Destination]

Database Schema Analysis

Schema Documentation

## Table: {TABLE_NAME}

### Columns
| Column | Type | Nullable | Default | Description |
|--------|------|----------|---------|-------------|
| id | bigint | No | auto | Primary key |

### Constraints
| Name | Type | Definition |
|------|------|------------|
| pk_table | Primary Key | (id) |
| fk_user | Foreign Key | user_id → users(id) |
| chk_status | Check | status IN ('A', 'I') |

### Indexes
| Name | Columns | Unique | Purpose |
|------|---------|--------|---------|
| idx_email | email | Yes | Lookup |

Integration Analysis

Integration Point Documentation

## Integration: {INTEGRATION_NAME}

### Overview
| Attribute | Value |
|-----------|-------|
| External System | {SYSTEM_NAME} |
| Integration Type | API / File / Message Queue / Database |
| Direction | Inbound / Outbound / Bidirectional |
| Frequency | Real-time / Batch / Event-driven |
| Protocol | REST / SOAP / SFTP / MQ / etc. |

### Data Exchange
| Data Element | Source | Destination | Transform |
|--------------|--------|-------------|-----------|
| Customer ID | System A | System B | Direct map |
| Order Total | System A | System B | Convert currency |

### Authentication
- Method: {AUTH_METHOD}
- Credentials: {CREDENTIAL_LOCATION}
- Rotation: {ROTATION_POLICY}

### Error Handling
| Error Type | Detection | Response | Retry |
|------------|-----------|----------|-------|
| Timeout | 30s limit | Log + Alert | 3x exponential |
| 4xx Error | Response code | Log + Skip | No retry |
| 5xx Error | Response code | Log + Alert | 3x exponential |

### SLA
- Availability: {UPTIME_REQUIREMENT}
- Response Time: {LATENCY_REQUIREMENT}
- Throughput: {VOLUME_REQUIREMENT}

### Monitoring
- Health Check: {ENDPOINT}
- Metrics: {METRICS_COLLECTED}
- Alerts: {ALERT_CONDITIONS}

Integration Pattern Analysis

Synchronous Patterns

• Request-Response: Direct API calls
• API Gateway: Centralized routing
• Service Mesh: Sidecar proxies

Asynchronous Patterns

• Message Queue: Point-to-point messaging
• Publish-Subscribe: Event distribution
• Event Sourcing: Event log as source of truth

Data Integration Patterns

• ETL: Extract, Transform, Load
• Change Data Capture: Real-time sync
• Data Virtualization: On-demand access

Security Analysis

Security Requirements Documentation

Authentication Analysis

## Authentication

### Current Implementation
- Method: {JWT / OAuth2 / SAML / etc.}
- Identity Provider: {IDP_NAME}
- Token Lifetime: {DURATION}
- Refresh Strategy: {STRATEGY}

### Multi-Factor Authentication
- Required For: {USER_TYPES}
- Methods: {MFA_METHODS}
- Bypass Conditions: {EXCEPTIONS}

### Session Management
- Timeout: {IDLE_TIMEOUT}
- Concurrent Sessions: {ALLOWED / PREVENTED}
- Session Storage: {MECHANISM}

Authorization Analysis

## Authorization

### Access Control Model
- Type: RBAC / ABAC / ACL / Custom

### Roles
| Role | Description | User Count |
|------|-------------|------------|
| Admin | Full access | 5 |
| Manager | Department access | 20 |
| User | Limited access | 500 |

### Permissions Matrix
| Resource | Admin | Manager | User |
|----------|-------|---------|------|
| Users | CRUD | R | - |
| Orders | CRUD | CRUD | CRU |
| Reports | CRUD | R | R |

### Business Rules
- {RULE_1}
- {RULE_2}

Data Protection Analysis

## Data Protection

### Sensitive Data Inventory
| Data Element | Classification | Protection |
|--------------|----------------|------------|
| Password | Secret | Hashed (bcrypt) |
| SSN | PII | Encrypted at rest |
| Credit Card | PCI | Tokenized |

### Encryption
- At Rest: {METHOD}
- In Transit: {METHOD}
- Key Management: {STRATEGY}

### Data Masking
| Field | Mask Type | Example |
|-------|-----------|---------|
| SSN | Partial | ***-**-1234 |
| Email | Partial | j***@***.com |

Compliance Analysis

## Compliance Requirements

### Applicable Regulations
| Regulation | Scope | Requirements |
|------------|-------|--------------|
| GDPR | EU users | Consent, Right to erasure |
| HIPAA | Health data | PHI protection |
| PCI-DSS | Payment data | Card data security |

### Compliance Controls
| Control | Implementation | Evidence |
|---------|----------------|----------|
| Access logging | Audit table | Logs |
| Encryption | AES-256 | Config |
| Retention | 7 years | Policy doc |

### Audit Requirements
- Audit logging enabled: {YES/NO}
- Retention period: {DURATION}
- Access review frequency: {FREQUENCY}

Infrastructure Analysis

Infrastructure Documentation

## Infrastructure Overview

### Environments
| Environment | Purpose | URL |
|-------------|---------|-----|
| Development | Dev testing | dev.app.com |
| Staging | Pre-prod testing | staging.app.com |
| Production | Live system | app.com |

### Compute
| Component | Type | Specs | Count |
|-----------|------|-------|-------|
| Web Server | VM/Container | 4 CPU, 8GB | 3 |
| API Server | Container | 2 CPU, 4GB | 5 |
| Database | RDS | db.r5.large | 2 |

### Networking
- VPC/VNET: {NETWORK_ID}
- Subnets: {SUBNET_LIST}
- Load Balancer: {LB_TYPE}
- CDN: {CDN_PROVIDER}

### Storage
| Type | Purpose | Size | Backup |
|------|---------|------|--------|
| RDS | Primary DB | 500GB | Daily |
| S3 | File storage | 1TB | Cross-region |
| Redis | Cache | 10GB | None |

Analysis Output Summary

After technical analysis, document:

1. API Contracts: All endpoints with schemas 2. Data Models: Entities, relationships, constraints 3. Integrations: External systems, data flows 4. Security: Auth, authorization, data protection 5. Infrastructure: Compute, storage, networking 6. Technical Debt: Issues and recommendations

See integration-patterns.md for common integration patterns.

Integration Patterns Reference

Synchronous Integration Patterns

Request-Response (REST/HTTP)

[Client] ──HTTP Request──> [Server]
[Client] <──HTTP Response── [Server]

Use When:

• Immediate response required
• Simple point-to-point integration
• Low latency tolerance

Considerations:

• Tight coupling between systems
• Failure impacts caller directly
• Need timeout handling
• Connection pool management

Requirement Implications:

• Define timeout requirements
• Specify retry behavior
• Document error response handling
• Establish SLA expectations

API Gateway Pattern

                    ┌─> [Service A]
[Client] ──> [Gateway] ─> [Service B]
                    └─> [Service C]

Use When:

• Multiple backend services
• Cross-cutting concerns (auth, logging)
• Rate limiting needed
• Protocol translation required

Considerations:

• Single point of failure
• Added latency
• Gateway must scale with traffic

Requirement Implications:

• Document routing rules
• Specify authentication flow
• Define rate limits
• Establish monitoring requirements

Service Mesh Pattern

[Service A + Sidecar] <──> [Service B + Sidecar]
         │                        │
         └────── [Control Plane] ─┘

Use When:

• Complex microservices environment
• Need service-to-service security
• Advanced traffic management
• Observability requirements

Considerations:

• Infrastructure complexity
• Resource overhead
• Operational expertise needed

Asynchronous Integration Patterns

Message Queue (Point-to-Point)

[Producer] ──> [Queue] ──> [Consumer]

Use When:

• Decoupled processing
• Load leveling needed
• Guaranteed delivery required
• Order matters (FIFO)

Considerations:

• Message persistence
• Dead letter handling
• Exactly-once vs at-least-once
• Queue depth monitoring

Requirement Implications:

• Define message retention
• Specify delivery guarantees
• Document ordering requirements
• Establish DLQ handling

Publish-Subscribe

                    ┌─> [Subscriber A]
[Publisher] ──> [Topic] ─> [Subscriber B]
                    └─> [Subscriber C]

Use When:

• Multiple consumers for same event
• Loose coupling required
• Fan-out pattern needed
• Event notification scenarios

Considerations:

• Message ordering per partition
• Subscriber management
• Replay capability
• Consumer group handling

Requirement Implications:

• Define event schema/contract
• Specify subscriber filtering
• Document replay requirements
• Establish schema versioning

Event Sourcing

[Command] ──> [Event Store] ──> [Read Model]
                   │
                   └── [Event 1, Event 2, Event 3...]

Use When:

• Complete audit trail needed
• Temporal queries required
• Event replay capabilities
• Complex domain logic

Considerations:

• Event schema evolution
• Eventual consistency
• Storage requirements
• Rebuild time for projections

Requirement Implications:

• Define event versioning strategy
• Specify consistency requirements
• Document snapshot strategy
• Establish replay procedures

CQRS (Command Query Responsibility Segregation)

[Commands] ──> [Write Model] ──> [Event Bus] ──> [Read Model] <── [Queries]

Use When:

• Different read/write patterns
• High read scalability needed
• Complex write validation
• Multiple read representations

Considerations:

• Eventual consistency
• Synchronization complexity
• Data duplication

Data Integration Patterns

ETL (Extract, Transform, Load)

[Source] ──Extract──> [Staging] ──Transform──> [Target]
                                      │
                                   [Load]

Use When:

• Batch data processing
• Data warehousing
• Historical data migration
• Scheduled synchronization

Considerations:

• Processing window constraints
• Data volume impacts
• Error handling and recovery
• Data quality validation

Requirement Implications:

• Define batch schedule
• Specify data validation rules
• Document error handling
• Establish data retention

Change Data Capture (CDC)

[Source DB] ──Change Log──> [CDC Tool] ──> [Target]

Use When:

• Near real-time sync needed
• Minimal source impact required
• Incremental changes tracking
• Event generation from DB

Considerations:

• Log retention requirements
• Schema change handling
• Performance impact on source

Data Virtualization

[Client] ──Query──> [Virtualization Layer] ──> [Source A]
                            │
                            └──> [Source B]

Use When:

• On-demand data access
• Multiple data sources
• No data movement desired
• Real-time data needed

Considerations:

• Query performance
• Source availability dependency
• Complex joins across sources

File-Based Integration Patterns

Batch File Transfer

[System A] ──> [File] ──> [Transfer] ──> [System B]
                              │
                          [SFTP/S3]

Use When:

• Legacy system integration
• Large data volumes
• Non-real-time acceptable
• Simple implementation needed

Considerations:

• File format standards
• Transfer security
• Acknowledgment handling
• Error file management

Requirement Implications:

• Define file format spec
• Specify naming conventions
• Document transfer schedule
• Establish reconciliation process

Shared Database

[System A] ──Read/Write──> [Database] <──Read/Write── [System B]

Use When:

• Tight integration needed
• Simple architecture desired
• Same technology stack

Considerations:

• Schema coupling
• Concurrency issues
• Performance contention
• Schema change coordination

Anti-pattern warning: Generally avoid - creates tight coupling

Error Handling Patterns

Retry with Exponential Backoff

Attempt 1 ── Fail ── Wait 1s
Attempt 2 ── Fail ── Wait 2s
Attempt 3 ── Fail ── Wait 4s
Attempt 4 ── Success

Implementation:

• Initial delay
• Multiplier
• Maximum retries
• Maximum delay cap
• Jitter for thundering herd

Circuit Breaker

[Closed] ──Failures exceed threshold──> [Open]
   ^                                        │
   │                                        │
   └──Success──[Half-Open]<──Timeout────────┘

States:

• Closed: Normal operation
• Open: Fail fast, no calls
• Half-Open: Limited testing

Configuration:

• Failure threshold
• Timeout duration
• Success threshold for recovery

Dead Letter Queue

[Queue] ──Process──> [Consumer]
   │                     │
   │                  [Fail]
   │                     │
   └─────────────> [DLQ] ──> [Alert/Manual Review]

Handling:

• Move failed messages
• Preserve original message
• Add failure metadata
• Enable replay

Security Patterns

OAuth2 / OpenID Connect

[Client] ──> [Auth Server] ──> [Token]
                                  │
[Client] + Token ──> [Resource Server]

Flows:

• Authorization Code (web apps)
• Client Credentials (service-to-service)
• Implicit (deprecated)
• Device Code (IoT)

API Key Authentication

[Client] + API-Key Header ──> [API Gateway] ──> [Backend]

Use When:

• Simple integration needed
• Server-to-server calls
• Rate limiting by key

mTLS (Mutual TLS)

[Client + Cert] <──Verify──> [Server + Cert]

Use When:

• Zero-trust networking
• High security requirements
• Service mesh environments

Integration Analysis Checklist

When analyzing integrations, document:

• [ ] Integration type: Sync/Async/File/Database
• [ ] Protocol: REST/SOAP/MQ/SFTP/etc.
• [ ] Authentication: OAuth/API Key/mTLS/etc.
• [ ] Data format: JSON/XML/CSV/Binary
• [ ] Error handling: Retry/Circuit breaker/DLQ
• [ ] Monitoring: Health checks/Metrics/Alerts
• [ ] SLA: Availability/Latency/Throughput
• [ ] Security: Encryption/Access control/Audit
• [ ] Data mapping: Field transformations
• [ ] Dependencies: External systems required