Architecture & Data Flow

Architecture

Petunia follows a Microservice-like architecture, containerized with Docker.

Components

Service	Container Name	Description
App	petunia_app	Python 3.12 environment containing Core Logic, Managers, and Scripts.
Database	petunia_db	PostgreSQL 16 instance storing OHLCV data, Portfolio state, and Trade history.
Dashboard	petunia_dashboard	Streamlit UI for data visualization and system control.

---

Data Flow Timeline

🟢 Daily Routine (Monday - Friday)

• Runs services/daily_run.py.
• Updates OHLC data and Portfolio Valuation (Mark-to-Market).
• Shadow Sync: Executes pending orders from Google Sheets if limits are hit.

🔴 Weekly Routine (Weekend)

• Runs services/weekly_run.py.
• Strategy Engine: Selects active strategy via Config (Default: RSI).
• Risk Manager: Calculates Position Size (2% Rule) & Stop Loss.
• Report: Pushes new orders to Google Sheets for review.

---

Data Flow Pipeline

1. Data Ingestion (ETL)

• Source: Yahoo Finance (via yfinance).
• Trigger: daily_run.py.
• Process: Fetch OHLCV -> Clean/Normalize -> Upsert to PostgreSQL (ohlc table).

2. Strategy Engine

• Trigger: weekly_run.py or backtest.py.
• Input: Historical Data from DB.
• Process: The active Strategy (EMA or RSI) computes indicators and outputs a DataFrame of Signals (BUY/SELL/HOLD).
• Validation: Signals are validated against a strict Schema Contract.

3. Risk & Execution

• Input: Raw Signals + Portfolio State (Cash/Positions).
• Process: The Risk Manager filters signals and calculates Position Size.
• Output: "Shadow Orders" are sent to the Google Sheet (Orders tab).

4. Shadow Synchronization

• Trigger: daily_run.py.
• Process: Checks pending orders in Google Sheet. If current market price hits the Limit Price, the trade is executed in the local DB and cleared from the Cloud.