admin/stonks-oracle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: comprehensive docs, unit tests, docker-compose app services

Browse Source 
- Add scheduler and ingestion unit tests (test_scheduler_unit.py, test_ingestion_unit.py)
- Add all 13 app services + dashboard to docker-compose.yml
- Add full documentation suite: API reference, Helm reference, Docker deployment guide,
  3 architecture diagrams (K8s, Docker Compose, data pipeline), AI agent guide,
  backup/restore guide, observability/metrics reference, per-service docs
- Add intelligence pipeline deep-dive docs with Mermaid diagrams
- Update README with documentation index and links
- Add specs for comprehensive-quality-docs, intelligence-pipeline-deep-dive,
  sanitized-pipeline-docs
This commit is contained in:
Celes Renata
2026-04-22 02:56:41 +00:00
parent f251c53f92
commit 88ad1e8d99
57 changed files with 13318 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+55 -34
View File
@@ -8,6 +8,21 @@ Licensed under the [Business Source License 1.1](LICENSE). Production use requir
AI-powered market intelligence and autonomous paper-trading platform. Ingests market data, company news, and regulatory filings; extracts structured intelligence with local LLMs; aggregates signals across three layers (company, macro, competitive); and autonomously executes paper trades — all self-hosted on Kubernetes.
## Documentation
| Document | Description |
|----------|-------------|
| [Service Reference](docs/services.md) | All 13 services — purpose, configuration, queue topology, database tables |
| [API Reference](docs/api-reference.md) | Complete endpoint reference for Query API, Symbol Registry, Trading, and Risk services |
| [Helm Chart Reference](docs/helm-reference.md) | All Helm values: services, config, secrets, ingress, network policies, analytics stack |
| [Docker Deployment Guide](docs/docker-deployment.md) | Docker Compose setup, environment variables, volumes, operational commands |
| [Kubernetes Architecture](docs/architecture-kubernetes.md) | Mermaid diagram of the K8s deployment topology, namespaces, ingress, and secrets |
| [Docker Compose Architecture](docs/architecture-docker-compose.md) | Mermaid diagram of all containers, port mappings, volumes, and dependencies |
| [Data Pipeline Architecture](docs/architecture-data-pipeline.md) | Mermaid diagram of the end-to-end data pipeline, queue topology, and signal layers |
| [AI Agents Guide](docs/ai-agents.md) | Built-in agents, variant management, prompt tuning, and performance monitoring |
| [Backup & Restore Guide](docs/backup-restore.md) | Backup scripts, restore procedures, retention policies, and disaster recovery |
| [Observability Reference](docs/observability.md) | Prometheus metrics, alerting rules, structured logging, and dead-letter queues |
## What It Does
Stonks Oracle tracks 50 companies across 10 sectors. It monitors multiple data sources, runs every article and filing through a local Ollama model to extract structured intelligence, aggregates those signals into rolling trend summaries with contradiction detection, and generates explainable trade recommendations. An autonomous trading engine then evaluates those recommendations and executes paper trades through Alpaca without manual intervention.
@@ -16,41 +31,47 @@ Everything is auditable — raw artifacts, prompts, model outputs, decision trac
## Architecture
```mermaid
flowchart LR
subgraph sources ["Data Sources"]
polygon["Polygon.io"]
sec["SEC EDGAR"]
macro_src["Macro News"]
end
subgraph pipeline ["Signal Processing"]
scheduler["Scheduler"]
ingestion["Ingestion"]
parser["Parser"]
extractor["Extractor"]
aggregation["Aggregation"]
recommendation["Recommendation"]
end
subgraph trading ["Trading"]
risk["Risk Engine"]
engine["Trading Engine"]
broker["Broker Adapter"]
alpaca["Alpaca (paper)"]
end
subgraph analytics ["Analytics"]
lake["Lake Publisher"]
trino["Trino"]
superset["Superset"]
dashboard["Dashboard"]
end
sources --> scheduler --> ingestion --> parser --> extractor --> aggregation --> recommendation
recommendation --> risk --> engine --> broker --> alpaca
aggregation --> lake --> trino --> superset
trino --> dashboard
```
┌──────────────────────────────────────────┐
│ Signal Aggregation │
│ │
┌───────────┐ ┌──────────┐ │ ┌──────────┐ ┌────────────────┐ │
│ Scheduler │─▶│Ingestion │─▶│ │ Parser │─▶│ Extractor │ │
└───────────┘ └──────────┘ │ └──────────┘ └──────┬─────────┘ │
│ │ │
│ ┌─────────────┘ │
│ ▼ │
│ ┌─────────────┐ ┌────────────────┐ │
│ │ Aggregation │───▶│ Recommendation │ │
│ └──────┬──────┘ └───────┬────────┘ │
│ │ │ │
│ Macro signals Competitive │
│ + Competitive signals │
│ signals merged │
└──────────────────────────────────────────┘
│
┌───────────────────────┘
▼
┌─────────────┐ ┌────────────────┐ ┌──────────────┐
│ Risk Engine │───▶│ Trading Engine │───▶│Broker Adapter│
└─────────────┘ └────────────────┘ └──────────────┘
│
┌────────────────┐ ┌──────────┘
│ Lake Publisher │ ▼
└───────┬────────┘ Alpaca (paper)
│
┌──────────────┼──────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌───────────┐
│ Trino │ │ Superset │ │ Dashboard │
└──────────┘ └──────────┘ └───────────┘
```
For detailed architecture diagrams see:
- [Kubernetes Deployment](docs/architecture-kubernetes.md)
- [Docker Compose Deployment](docs/architecture-docker-compose.md)
- [Data Pipeline](docs/architecture-data-pipeline.md)
Two planes:
- **Operational** — ingestion, parsing, extraction, aggregation, recommendations, risk evaluation, autonomous trading, trade execution (PostgreSQL, Redis, MinIO)