Implementation Plan

This document outlines the phased approach for implementing the Weekly Trading App, with a focus on iterative development and early validation.

Epic 1: Core Infrastructure

1.1 Project Setup

• [x] Set up GitHub repository with branch protection
• [x] Configure GitHub Actions for CI/CD
• [x] Create Docker configuration
• [→] Set up development environment & Practices
  • [x] VS Code Settings
  • [x] DevContainers for day-to-day (docker-in-docker)
  • [x] Dependencies (WSL, Docker Desktop, VS Code)
  • [x] Contributing
  • [→] Live Share
  • [x] GH CLI Tool (then remove globally)
  • [x] Project Epics
  • [x] GitHooks code quality
• [x] Implement logging framework (Phase 1 & 2 complete)
  • [x] Setup Grafana account (stack + service account + API key)
  • [x] Add GitHub prod secrets: GRAFANA_OTLP_ENDPOINT, GRAFANA_API_KEY (optional: GRAFANA_LOKI_ENDPOINT)
  • [x] Create local .env.example with Grafana placeholders; DEPLOYMENT_ENVIRONMENT=dev
  • [x] Add resource attributes (service.name, deployment.environment) in API/Engine
  • [x] Structured JSON logging with trace correlation fields
  • [x] Expose /metrics with Prometheus format (API port 8000, Engine port 8080)
  • [x] Configure OTLP exporters (traces) to Grafana Cloud Tempo
  • [x] Per-service venvs for import resolution (multi-root workspace)
  • [x] API tests passing (metrics, root endpoint, span creation)
  • [x] Create initial Grafana dashboards filtered by deployment.environment
  • [x] Implemented observability compose profile (default in dev)
    • [x] Prometheus scraping services → Remote Write to Grafana Cloud Mimir
    • [x] Promtail shipping logs to Grafana Cloud Loki
    • [x] Made observability default dev profile (web,observability)
    • [ ] (Phase 3) Add OpenTelemetry Collector for unified pipeline
  • [ ] Wiring GitHub Environment secrets in deployment workflows

1.2 VitePress Documentation Setup

• [x] Set up VitePress site structure (docs/.vitepress/config.ts, navigation, mermaid plugin)
• [x] Migrate architecture documentation (C4 models) to VitePress (render existing Mermaid diagrams)
• [x] add vitepress simple search
• [x] Create templates for strategy documentation (reference paths; no code duplication)
• [x] Configure CI/CD for automated static build
• [x] Secure pages for team only.
• [x] Set up documentation deployment target (static hosting or CDN)

1.3 API Exploration

• [ ] Research Yahoo Finance API structure and endpoints
• [ ] Research Alpha Vantage API structure and endpoints
• [ ] Document data schemas from both providers in VitePress
• [ ] Identify common elements and provider-specific fields
• [ ] Determine transformation needs for standardization
• [ ] Document findings and decisions in VitePress

1.4 Data Layer Design

• [ ] Design common data model that normalizes across providers
• Define database schema for:
  • [ ] Historical price data (OHLCV structure)
  • [ ] Weekly pivots and other calculated values
  • [ ] Trade records and signals
• [ ] Design Database Abstraction Layer interfaces based on these models
• [ ] Document data model and interfaces in VitePress

1.5 Data Layer Implementation

• [ ] Implement Database Abstraction Layer
• [ ] Create provider-specific adapters
• [ ] Implement storage backends (NoSQL, Parquet)
• [ ] Create ETL pipeline for historical data
• [ ] Set up scheduled jobs for data refresh

1.6 Deployment (Dev → Staging → Prod)

• [ ] Choose cloud subscription and region
• [ ] Provision base resources (resource group, container registry, container apps environment, log analytics, key vault)
• [ ] Register deployment environments in GitHub (dev, staging, prod) with protection rules
• [ ] Configure GitHub Actions OIDC federation and least-privilege roles
• [ ] Define deployment configuration (image repo, environment variables, secrets sourced from vault)
• [ ] Add deployment workflow(s) under .github/workflows/ (manual for dev; tag-based for staging/prod)
• [ ] Document runbooks in docs/devops/deployment.md

1.7 Security & Access Control

• [ ] Auth0 tenant and applications created (SPA for Web UI; API audience defined)
• [ ] Configure OIDC PKCE in Web UI (Auth0 Universal Login, callback/logout URLs per environment)
• [ ] Backend API JWT validation (RS256) using Auth0 JWKS; enforce scopes on protected routes
• [ ] Environment configuration documented (Auth0 domain, audience, client id) and mapped per environment
• [ ] Add basic user profile storage (optional) and tie to app roles/permissions (future)

Epic 2: Strategy Engine

2.1 Strategy Framework

• [ ] Define strategy interface/abstract class
• [ ] Implement backtesting engine
• [ ] Create performance metrics calculation
• [ ] Build strategy serialization/deserialization
• [ ] Document framework design in VitePress

2.2 First Strategies

• [ ] Implement weekly pivot calculation
• [ ] Create basic weekly trading strategy
• [ ] Build visualization for strategy results
• [ ] Implement strategy parameter optimization
• [ ] Document strategy implementations with backtest results in VitePress

Epic 3: User Interface

3.1 API Layer

• [ ] Create REST API endpoints
• [ ] Implement authentication
• [ ] Build WebSocket for real-time updates
• [ ] Document API specifications in VitePress

3.2 Svelte UI

• [ ] Set up Svelte project
• [ ] Implement dashboard components
• [ ] Create strategy configuration UI
• [ ] Build reporting and visualization screens
• [ ] Document UI components and usage

Epic 4: Refinement & Extensions

4.1 Testing & Performance

• [ ] Comprehensive testing
• [ ] Performance optimization
• [ ] Scale testing with larger datasets
• [ ] Document performance benchmarks and test results

4.2 Additional Features

• [ ] Advanced analytics
• [ ] Improved visualizations
• [ ] Additional strategies
• [ ] Prepare for AI/ML integration
• [ ] Document feature extensions and ML readiness

Epic: Future Phases

Trade Execution

• [ ] Implement broker API client(s)
• [ ] Build order management system
• [ ] Create position tracking
• [ ] Implement risk management rules
• [ ] Document integration details and risk controls in VitePress

Automation Framework

• [ ] Build event-driven trading engine
• [ ] Implement trade signal generation
• [ ] Create trade execution engine
• [ ] Set up monitoring and alerts
• [ ] Document automation framework and event handlers

Milestones

1. Alpha Version (End of Phase 2)

   • [ ] Historical data storage and retrieval
   • [ ] Basic strategy backtesting
   • [ ] Weekly pivot calculation
   • [ ] Complete VitePress documentation of architecture and first strategy
   • [ ] Initial dev deployment (API + data) reachable via cloud endpoint
   • [ ] Auth enabled in dev (SPA login via Auth0; API validates JWT)

2. Beta Version (End of Phase 3)

   • [ ] End-to-end workflow for backtesting
   • [ ] Strategy visualization
   • [ ] Basic UI for monitoring results
   • [ ] Strategy documentation with backtest results
   • [ ] Staging deployment with environment approvals
   • [ ] Auth flows validated end-to-end in staging

3. MVP Release (End of Phase 4)

   • [ ] Complete UI
   • [ ] Multiple backtestable strategies
   • [ ] Comprehensive documentation for all components
   • [ ] Performance optimization
   • [ ] Production deployment with rollback plan documented

4. Future Release

   • [ ] Trade execution integration
   • [ ] Live trading capability
   • [ ] AI/ML integration
   • [ ] Complete documentation with performance metrics and ML readiness

Implementation Notes

Documentation First Approach

• VitePress documentation precedes implementation to clarify requirements
• API findings and decisions are documented immediately
• Strategy documentation includes rationale, backtest results, and ML readiness
• Documentation is treated as a first-class deliverable with CI/CD automation

Data Storage Design Considerations

• Start with a simple adapter pattern for data sources
• Use common models across the application
• Consider using SQLAlchemy for SQL databases, Motor for MongoDB, PyArrow for Parquet
• Plan for both batch and streaming data processing

Strategy Implementation

• Start with rule-based strategies
• Document each strategy according to the strategy template
• Version control all strategy configurations
• Prepare for future machine learning enhancements

Testing Approach

• Unit tests for all components
• Integration tests for data flow
• Backtesting as validation
• Performance benchmarks for critical paths