--- name: system-architecture-analysis description: >- 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: ```markdown # [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.