5.6 KiB
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
-
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.
-
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).
-
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
useEffectdependencies, 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 (
EXPLAINqueries), avoidance ofSELECT *on large tables, and optimization ofJOINchains. - 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
.envconfiguration keys, Docker container mappings, and database schemas. - Provide concrete code diffs or SQL migration examples alongside analytical recommendations.