Crate Structure, Error Handling, Configuration & Type Hierarchy

import { Tabs, TabItem } from ‘@astrojs/starlight/components’;

14. Crate Structure & Module Layout

Dependency Flow Rule

Las dependencias son estrictamente acíclicas y unidireccionales:

cvx-server → cvx-api → cvx-query → cvx-index
                      ↘ cvx-ingest → cvx-index
                        cvx-query → cvx-analytics → cvx-storage
                        cvx-query → cvx-storage
                                     cvx-index → cvx-core
                                     cvx-storage → cvx-core
                                     cvx-ingest → cvx-core
                                     cvx-analytics → cvx-core

cvx-core no depende de ningún otro crate del workspace. Todos los demás dependen de cvx-core.

---

15. Error Handling Strategy

Principios:

• CvxError implementa std::error::Error + Display + Send + Sync + 'static.
• Cada crate define su propio tipo de error (e.g., StorageError) que implementa Into<CvxError>.
• En la API, los errores se mapean a códigos HTTP/gRPC apropiados.
• Los errores internos incluyen context (via thiserror) pero nunca se exponen al cliente (se logean y se devuelve un error genérico).

---

16. Configuration & Feature Flags

Compile-Time Feature Flags (Cargo features)

[features]
default = ["rest-api", "grpc-api", "hot-storage", "simd-auto"]

# API
rest-api = ["axum", "tower-http"]
grpc-api = ["tonic", "prost"]

# Storage tiers
hot-storage = ["rocksdb"]
warm-storage = ["parquet", "arrow"]
cold-storage = ["object_store"]

# Compute
simd-auto = []           # Auto-vectorization only
simd-explicit = ["pulp"] # Explicit SIMD via pulp
gpu-compute = ["burn/cuda"]

# Analytics
neural-ode = ["burn"]
pelt = []
bocpd = []

# Metrics
poincare = []  # Hyperbolic distance support

# Distributed
distributed = ["openraft"]

---

19. Key Trait & Type Hierarchy

---

20. Cross-Cutting Concerns

20.1 Backpressure

20.2 Graceful Shutdown

20.3 Idempotency

Cada punto ingestado se identifica por la tupla (entity_id, timestamp). Re-insertar el mismo punto es idempotente: el WAL asigna un sequence number, y si la tupla ya existe en el store, se verifica que el vector sea idéntico (via xxhash). Si difiere, se trata como una corrección y se actualiza atómicamente.

20.4 Security Boundaries (Future)