101 lines
5.6 KiB
Markdown
101 lines
5.6 KiB
Markdown
---
|
|
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.
|