a2host/.agents/skills/system-architecture-analysis/SKILL.md

5.6 KiB

name description
system-architecture-analysis Provides comprehensive software architecture analysis, performance profiling, system diagnostics, technical trade-off evaluation, and bottleneck discovery across frontend, backend, database, and LLM/AI integrations. Use when assessing system health, planning refactors, analyzing complex workflows, or auditing security.

System Architecture & Technical Analysis Skill

This skill establishes the methodology for analyzing, diagnosing, and evaluating complex full-stack web architectures, APIs, and AI integrations.


1. Core Analytical Principles

  1. Evidence-Based Diagnosis:

    • Always base findings on actual code, queries, configurations, and profiles—never assumptions.
    • Trace end-to-end data flows from client input -> WebSocket/HTTP transport -> business logic -> database/external services -> client rendering.
  2. Holistic Layer Breakdown: Analyze systems across four interdependent layers:

    • Client/UI Layer: DOM performance, state reactivity, bundle footprint, WebSocket lifecycle.
    • Transport & Communication: WebSocket protocols, HTTP/REST endpoints, serialization overhead, connection pooling.
    • Server & Domain Logic: Execution time, memory footprint, concurrency, security boundaries, rate limits.
    • Persistence & Integration: Database query plans, indexing, connection pooling, external API latencies (CRONODE, Gemini LLM, Vector Search).
  3. Trade-Off Evaluation Matrix: When evaluating architecture decisions, compare options across 5 dimensions:

    • Performance & Latency (time-to-first-token, query execution time).
    • Maintainability & Complexity (cognitive overhead, coupling vs. cohesion).
    • Scalability & Resource Usage (memory limits, connection limits, CPU usage).
    • Security & Data Isolation (authentication, least privilege, auditability).
    • Reliability & Fault Tolerance (fallback paths, graceful degradation).

2. Layer-Specific Diagnostics Checklist

A. Frontend & UI (Astro + React + Tailwind)

  • State & Lifecycle: Verify useEffect dependencies, avoidance of redundant re-renders, and proper cleanup of event listeners / timers / WebSocket subscribers.
  • Bundle & Rendering: Check bundle splitting, lazy loading of heavy modals/panels (React.lazy), and font/asset optimization.
  • Responsive Stability: Test viewport boundaries (320px, 768px, 1024px, 1440px+), safe-area insets, and touch target sizing.
  • Memory & DOM: Verify cleanup of object URLs (URL.revokeObjectURL), abort controllers on unmount, and virtualized/paginated large lists.

B. Transport & WebSocket Layer (Ratchet / Swoole / Native Sockets)

  • Message Protocol: Validate structured JSON payload envelopes (type, payload, timestamp, session_id).
  • Heartbeat & Reconnection: Inspect ping/pong keepalive intervals, exponential backoff reconnection strategies, and offline queueing.
  • Streaming Pipeline: Verify chunk handling, backpressure management, and typing indicator state transitions.

C. Backend Domain & Security (PHP 8.2+)

  • Authentication & Authorization: Verify JWT token expiration, signature algorithm integrity, role-based access checks (roles, categoria_acceso).
  • Input Sanitization & Injection Defense: Parameterized queries via PDO, XSS prevention in Markdown/HTML parsing, path traversal checks.
  • Rate Limiting & Abuse Prevention: Sliding window rate limits on chat messages, login attempts, and external API calls.
  • Error Handling: Graceful error logging without exposing stack traces or database schema details to clients.

D. Persistence & AI Search (MySQL 8.0 & Vector Embeddings)

  • Query Performance: Check index utilization (EXPLAIN queries), avoidance of SELECT * on large tables, and optimization of JOIN chains.
  • Transaction Integrity: Use ACID transactions for multi-table updates (audit_log, ticket_support, user edits).
  • Vector & Semantic Search: Verify cosine similarity thresholds, embedding model versions (gemini-embedding-2), and batch indexing strategies.

3. Analysis Deliverable Template

When presenting technical analyses or reports to users or in artifacts:

# [Component / Feature] Technical Architecture Analysis

## 1. Executive Summary
Brief 2-3 sentence overview of system state, major findings, and strategic recommendation.

## 2. Architecture Topology & Data Flow
- Describe or diagram the end-to-end path (Client -> WS -> Logic -> DB/LLM).
- Identify critical path operations and dependencies.

## 3. Key Findings & Diagnostic Matrix
| Component | Status | Finding / Bottleneck | Impact | Severity |
| :--- | :---: | :--- | :--- | :---: |
| e.g. Chat WS | ⚠️ | Missing backpressure on stream | High CPU on burst | Medium |
| e.g. Cronode Query | ✅ | Cached with TTL (14400s) | Optimal latency | None |

## 4. Security & Edge Case Evaluation
- Identified vulnerabilities or security boundary checks.
- Handling of network partitions, timeouts, and quota exhausts.

## 5. Strategic Recommendations & Action Plan
1. **Immediate (P0)**: Critical fixes impacting stability or security.
2. **Short-Term (P1)**: Performance optimizations and refactoring.
3. **Long-Term (P2)**: Architectural improvements for scalability.

4. Best Practices for Antigravity Agents

  • Always inspect active code before drawing architectural conclusions.
  • Cross-reference .env configuration keys, Docker container mappings, and database schemas.
  • Provide concrete code diffs or SQL migration examples alongside analytical recommendations.