{ "version": "1.0", "date": "2026-08-06", "owner": "Platform Architecture", "description": "Master data contract for K-ArtSell Aegis v16.0 - defines schema, PIT rules, and DQ lineage", "governance": "AGENTS.md v16.0 compliant; all tables MUST follow PIT envelope pattern", "pit_envelope": { "description": "Point-in-Time data consistency model", "columns": { "published_at": { "type": "timestamp", "nullable": false, "default": "now()", "purpose": "Record publication timestamp for historical querying" }, "correlation_id": { "type": "uuid", "nullable": false, "purpose": "Trace changes across modules (Outbox→Inbox)" }, "revision": { "type": "integer", "nullable": false, "default": 1, "purpose": "Track revision count (immutable + versioning)" } }, "query_pattern": "SELECT * FROM table WHERE published_at <= @cutoff AND status = 'active' ORDER BY published_at DESC LIMIT 1" }, "tables": [ { "name": "model_operations.models", "owner": "ModelOperations Module", "purpose": "Master record of AI models (lifecycle: Freeze→Mature→Score→Diagnose→Hypothesis→Challenger→Validate→Review→Manual)", "columns": { "model_id": {"type": "uuid", "nullable": false, "key": "primary", "example": "00000000-0000-0000-0000-000000000001"}, "name": {"type": "varchar(255)", "nullable": false, "example": "GARCH-Vol-Predictor-v1"}, "status": {"type": "varchar(50)", "nullable": false, "enum": ["Freeze", "Mature", "Score", "Diagnose", "Hypothesis", "Challenger", "Validate", "Review", "ManualActivation"], "dq_rule": "Must be exact enum value (case-sensitive)"}, "version": {"type": "integer", "nullable": false, "dq_rule": "Increment on each state transition"}, "created_at": {"type": "timestamp", "nullable": false}, "created_by": {"type": "varchar(255)", "nullable": false, "dq_rule": "Must match authenticated user"}, "published_at": {"type": "timestamp", "nullable": false, "pit": true}, "correlation_id": {"type": "uuid", "nullable": false, "pit": true}, "revision": {"type": "integer", "nullable": false, "pit": true} }, "constraints": { "no_update": "All changes are new rows (append-only)", "no_delete": "Soft delete via status change only", "uniqueness": "Only one 'active' revision per model_id at any cutoff time" } }, { "name": "signal_engine.signals", "owner": "SignalEngine Module", "purpose": "Trading signals generated from model scoring", "columns": { "signal_id": {"type": "uuid", "nullable": false, "key": "primary"}, "model_id": {"type": "uuid", "nullable": false, "foreign_key": "model_operations.models(model_id)", "dq_rule": "Must reference valid model at published_at cutoff"}, "portfolio_id": {"type": "uuid", "nullable": false}, "signal_type": {"type": "varchar(50)", "nullable": false, "enum": ["BUY", "SELL", "HOLD"], "dq_rule": "Exact enum value"}, "confidence_score": {"type": "decimal(5,4)", "nullable": false, "dq_rule": "0.0000 ≤ score ≤ 1.0000"}, "issued_at": {"type": "timestamp", "nullable": false}, "expires_at": {"type": "timestamp", "nullable": true, "dq_rule": "If present, must be > issued_at"}, "published_at": {"type": "timestamp", "nullable": false, "pit": true}, "correlation_id": {"type": "uuid", "nullable": false, "pit": true}, "revision": {"type": "integer", "nullable": false, "pit": true} }, "constraints": { "referential_integrity": "model_id must exist at published_at ≤ signal's published_at", "temporal_validity": "issued_at must be ≤ published_at" } }, { "name": "market_data.prices", "owner": "KRX API Integration", "purpose": "Daily OHLCV (Open, High, Low, Close, Volume) from Korea Exchange", "columns": { "price_id": {"type": "uuid", "nullable": false, "key": "primary"}, "symbol": {"type": "varchar(10)", "nullable": false, "dq_rule": "KRX stock code (6 digits for KOSPI, e.g., '005930' for Samsung)"}, "trade_date": {"type": "date", "nullable": false, "dq_rule": "Business day only (Mon-Fri, excluding holidays)"}, "open_price": {"type": "decimal(15,2)", "nullable": false, "dq_rule": "> 0"}, "high_price": {"type": "decimal(15,2)", "nullable": false, "dq_rule": "≥ close_price"}, "low_price": {"type": "decimal(15,2)", "nullable": false, "dq_rule": "≤ close_price"}, "close_price": {"type": "decimal(15,2)", "nullable": false, "dq_rule": "> 0"}, "volume": {"type": "bigint", "nullable": false, "dq_rule": "≥ 0; typically > 1000 shares for liquid stocks"}, "source": {"type": "varchar(50)", "nullable": false, "default": "KRX_OPENAPI", "dq_rule": "Immutable source attribution"}, "published_at": {"type": "timestamp", "nullable": false, "pit": true}, "correlation_id": {"type": "uuid", "nullable": false, "pit": true}, "revision": {"type": "integer", "nullable": false, "pit": true} }, "constraints": { "unique_per_day": "(symbol, trade_date) is unique", "price_ordering": "low_price ≤ open_price, close_price ≤ high_price", "no_future_dates": "trade_date ≤ today()" }, "sla": { "availability": "99.5%", "latency": "< 100ms (cached)", "freshness": "T+1 (end of business day)" } }, { "name": "portfolio.holdings", "owner": "Portfolio Module", "purpose": "User portfolio: assets owned, quantities, cost basis", "columns": { "holding_id": {"type": "uuid", "nullable": false, "key": "primary"}, "portfolio_id": {"type": "uuid", "nullable": false}, "symbol": {"type": "varchar(10)", "nullable": false}, "quantity": {"type": "decimal(15,4)", "nullable": false, "dq_rule": "> 0; fractional shares allowed"}, "cost_basis": {"type": "decimal(15,2)", "nullable": false, "dq_rule": "> 0 if quantity > 0"}, "acquisition_date": {"type": "date", "nullable": false, "dq_rule": "≤ today()"}, "published_at": {"type": "timestamp", "nullable": false, "pit": true}, "correlation_id": {"type": "uuid", "nullable": false, "pit": true}, "revision": {"type": "integer", "nullable": false, "pit": true} }, "constraints": { "logical_consistency": "If quantity = 0, holding is logically 'sold' (soft delete)", "cost_relationship": "total_cost = quantity × cost_basis (must reconcile with transactions)" } }, { "name": "audit.events", "owner": "Observability Module", "purpose": "Immutable event log for compliance and troubleshooting", "columns": { "event_id": {"type": "uuid", "nullable": false, "key": "primary"}, "event_type": {"type": "varchar(100)", "nullable": false, "enum": ["ModelActivated", "SignalIssued", "TradingExecuted", "ApprovalRequested"], "dq_rule": "Exact enum"}, "correlation_id": {"type": "uuid", "nullable": false, "pit": true, "dq_rule": "Links back to originating command"}, "actor_id": {"type": "uuid", "nullable": false, "dq_rule": "User/service that triggered event"}, "action": {"type": "text", "nullable": true, "dq_rule": "Serialized command payload (sanitized of PII)"}, "result": {"type": "varchar(50)", "nullable": false, "enum": ["Success", "Failure", "Pending"]}, "occurred_at": {"type": "timestamp", "nullable": false, "dq_rule": "Event time (not insertion time)"}, "published_at": {"type": "timestamp", "nullable": false, "pit": true}, "revision": {"type": "integer", "nullable": false, "pit": true, "default": 1} }, "constraints": { "immutable": "No updates allowed (INSERT ONLY)", "retention": "Kept for minimum 7 years (regulatory requirement)" } } ], "data_quality_rules": { "by_source": { "KRX_API": { "availability_sla": "99.5%", "completeness": "No null prices, volumes", "accuracy": "Must match official KRX reporting", "timeliness": "T+1 (end of business day)", "fallback": "Use cached last-known-good (LKG) if API fails" }, "OpenDart_API": { "availability_sla": "99.0%", "completeness": "Filing date, report type, corp_code must be non-null", "accuracy": "Must match official FSS (Financial Supervisory Service) repository", "timeliness": "T+2 (regulatory reporting)", "fallback": "Queue for retry (Hangfire job with exponential backoff)" }, "User_Input": { "availability_sla": "95.0% (user-provided, best effort)", "completeness": "Validated at API boundary (FastEndpoints validator)", "accuracy": "User's responsibility; audit trail required", "timeliness": "Real-time (synchronous)", "validation": "Qty ≥ 0, price ≥ 0, date ≤ today()" }, "Computed_Fields": { "availability_sla": "99.9% (auto-computed)", "completeness": "Guaranteed (computed from base fields)", "accuracy": "Deterministic (same input → same output)", "timeliness": "Refresh on event (Outbox→Inbox trigger)", "formula": "portfolio_value = SUM(qty × market_price) for active holdings" } } }, "lineage_and_dependencies": { "shadow_run": { "inputs": ["models", "prices", "holdings"], "outputs": ["shadow_run_results"], "duration": "252+ trading days", "sla": "99.9% completion (auto-retry on transient failures)" }, "signal_generation": { "inputs": ["models (Mature+)", "prices"], "outputs": ["signals"], "trigger": "Hangfire job (daily 09:00 KST)", "sla": "< 1 minute latency" }, "portfolio_rebalance": { "inputs": ["signals", "holdings", "prices"], "outputs": ["rebalance_recommendations"], "trigger": "User request or scheduled (weekly)", "approval": "Maker-checker (2-level approval)" } }, "compliance_and_security": { "gdpr_rules": [ "User PII (name, email, SSN) must be redacted in logs", "Audit trail must be immutable (audit.events is INSERT ONLY)", "Right to erasure: Soft delete via status field (logical delete, not physical)", "Data retention: Portfolio data kept for 5 years; audit kept for 7 years" ], "pci_dss_rules": [ "Credit card data NEVER stored (payment via third-party provider)", "All financial data encrypted at rest (PostgreSQL pgcrypto)", "API calls use HTTPS + TLS 1.2+ only", "No API key logging (masked in audit trail)" ], "audit_requirements": [ "All mutations (INSERT, UPDATE, soft-DELETE) logged to audit.events", "correlation_id traces change across services", "actor_id identifies responsible user/service", "action field captures sanitized command (PII redacted)" ] } }