docs: Add comprehensive UML architecture documentation for Criptotrade#67
Merged
Merged
Conversation
Recursive static analysis of the whole repository producing 18 UML diagrams (Mermaid + PlantUML): use case, packages, components, 8 layered class diagrams, 3 sequence diagrams, 2 activity flowcharts, HITL order state machine, and deployment. Documents the trading pipeline (Strategy->Risk->Guardrails->HITL->Execution), the cross-process HITL bridge over SQLite, the OpenAPI/openapi.d.ts contract linking the Python backend and React console, and infra spine (ledger/db/metrics/exchange). Includes traceability table (entity -> source file) and an architecture critique covering cohesion/coupling and refactoring opportunities (duplicate class names, the unused BuildToValue orchestration cluster, two agent base hierarchies, redundant order-validation policies). Notes the actual repo composition (Python-centric; React/JSX console; one generated TS contract file; no Rust) and adapts the requested multi-language methodology accordingly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017hpSLazvYy2mPm4QhR9B3r
Complements the class-level UML doc with an architecture-level view of the entire repository, using the C4 model plus supporting views: - C4 L1 System Context, L2 Containers, L3 Components (API + Loop) - Data architecture: ERD from migrations (orders, open_positions, circuit_breaker_state, cycle_events, backtest_jobs, journal_entries, ledger_events) + append-only file stores (ledger/XES/alerts/memory) - Data flow (signal -> order -> fill -> metrics), runtime/process view - Deployment topologies (dev, prod self-contained, VPS gateway) - CI/CD pipeline (Python CI + phase validation, OpenAPI drift gate) - Observability (Prometheus/Grafana, structured logs, XES process mining, SSE alerts) and security (network isolation, auth, guardrails, sandbox, secrets) - Architecture recommendations with a prioritized findings table and a proposed incremental target-state diagram All diagrams in Mermaid, validated for balanced fences/braces. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017hpSLazvYy2mPm4QhR9B3r
Maps every data element that flows through the whole repository — inputs, outputs, intermediate/state, and persisted data — across all languages present (Python, JSX/JS, the generated TypeScript contract, HTML, SQL, YAML, .env, Docker). Notes explicitly that no Rust code exists. Contents: - Env-var inventory (defaults, coercion, consumers) and YAML policy config - Persisted data: every SQL table/column + JSONL/JSON stores + the ledger event-store payload schema per event_type (the XES process log) - Canonical in-transit structures: the task/analysis/signal/market_data (both shapes)/strategy_result/risk_result/execution_result/Order dicts with exact keys and file:line - Per-module data catalog (agents, orchestration, strategies, analysis, backtest, risk, safety, core, hitl, memory, journal, tools, evaluation, consensus/routing/planning, protocols, utils) - API layer: DTOs, route I/O, middleware data; frontend CT_API + mock + per-screen state; the openapi.d.ts transversal contract - End-to-end lifecycle trace of a signal -> order -> fill -> metric - "Data lost in the class" (assigned-but-never-read) section, as requested - Data anomalies (two market_data shapes, entry->entry_price bridge, mean_reversion never selected, ab_tests.jsonl not valid JSON, etc.) Docs only; no source code changed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017hpSLazvYy2mPm4QhR9B3r
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a comprehensive architectural documentation file (
docs/uml/arquitetura-uml.md) that provides a complete analysis of the Criptotrade platform's structure, design patterns, and system interactions. The document serves as a reference guide for understanding the codebase organization, dependencies, and data flows across the Python backend, React frontend, and supporting infrastructure.Key Changes
Notable Implementation Details
ContinuousEvaluator,AdaptivePlanner,SquadOrchestrator)BaseAgentvsSafeAgentBase)https://claude.ai/code/session_017hpSLazvYy2mPm4QhR9B3r