# vijish18/godzilla architecture

> Architecture diagram of the GitHub repository vijish18/godzilla, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vijish18/godzilla
- Repository: https://github.com/vijish18/godzilla

## Overview

GodZilla is a research-first intraday quantitative trading platform for liquid NSE instruments. Its documented workflow runs from market observations through causal features and market-state routing to independent alpha strategies, ensemble normalization, and proposed portfolio targets. Supporting capabilities include universe construction, compliance and session metadata, and durable event replay. The README describes risk approval and execution as required future stages, but explicitly says they are not implemented; they are therefore not represented as runtime components. Edges cite README workflow statements or source-index references; unsampled subsystems are included only where the README documents them.

Main entry points: [`src/godzilla/features/engine.py`](https://github.com/vijish18/godzilla/blob/main/src/godzilla/features/engine.py) (Feature Engine), [`src/godzilla/app/cli.py`](https://github.com/vijish18/godzilla/blob/main/src/godzilla/app/cli.py) (CLI), [`src/godzilla/core/events/journal.py`](https://github.com/vijish18/godzilla/blob/main/src/godzilla/core/events/journal.py) (Event Journal), [`src/godzilla/market_data/service.py`](https://github.com/vijish18/godzilla/blob/main/src/godzilla/market_data/service.py) (Market Data Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market_inputs["Market Inputs"]
  node_calendar["NSE Calendar<br/>[calendar.py]"]
  node_instruments["Instrument Master<br/>[instruments.py]"]
  node_universe["Universe Builder<br/>[builder.py]"]
  node_market_data["Market Data Service<br/>[service.py]"]
  node_quality["Data Quality<br/>[quality.py]"]
end

subgraph group_signals["Features and Signals"]
  node_features["Feature Engine<br/>[engine.py]"]
  node_feature_service["Feature Publication<br/>[service.py]"]
  node_state_router["Market-State Router<br/>[router.py]"]
  node_momentum["Momentum Alpha"]
  node_pairs["Pairs Research<br/>[pairs_engine.py]"]
  node_other_alphas["Other Alpha Strategies"]
end

subgraph group_allocation["Alpha Allocation"]
  node_ensemble["Alpha Ensemble<br/>[normalize.py]"]
  node_allocator["Portfolio Allocator<br/>[allocator.py]"]
end

subgraph group_operations["Operations"]
  node_cli["CLI<br/>[cli.py]"]
  node_configuration["Configuration<br/>[loader.py]"]
  node_compliance["Compliance Profiles<br/>[service.py]"]
end

subgraph group_durability["Events and Storage"]
  node_event_journal["Event Journal<br/>[journal.py]"]
  node_event_replay["Event Replay<br/>[replay.py]"]
  node_postgres[("PostgreSQL Storage<br/>[postgres.py]")]
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_cli
node_cli -->|"loads"| node_configuration
node_cli -->|"validates"| node_compliance
node_cli -->|"loads"| node_instruments
node_cli -->|"builds"| node_universe
node_universe -->|"uses"| node_instruments
node_market_data -->|"checks observations"| node_quality
node_market_data -->|"uses sessions"| node_calendar
node_market_data -->|"provides observations"| node_features
node_features -->|"provides features"| node_state_router
node_features -->|"uses sessions"| node_calendar
node_feature_service -->|"publishes events"| node_event_journal
node_state_router -->|"routes permissions"| node_momentum
node_state_router -->|"supplies state"| node_pairs
node_state_router -.->|"routes permissions"| node_other_alphas
node_features -->|"supplies features"| node_momentum
node_features -->|"supplies features"| node_pairs
node_momentum -->|"supplies candidates"| node_ensemble
node_pairs -.->|"supplies candidates"| node_ensemble
node_other_alphas -->|"supplies candidates"| node_ensemble
node_ensemble -->|"provides decisions"| node_allocator
node_allocator -->|"publishes decisions"| node_event_journal
node_market_data -.->|"records events"| node_event_journal
node_event_journal -->|"persists through"| node_postgres
node_event_replay -.->|"replays events"| node_event_journal

click node_cli "https://github.com/vijish18/godzilla/blob/main/src/godzilla/app/cli.py"
click node_configuration "https://github.com/vijish18/godzilla/blob/main/src/godzilla/config/loader.py"
click node_compliance "https://github.com/vijish18/godzilla/blob/main/src/godzilla/compliance/service.py"
click node_calendar "https://github.com/vijish18/godzilla/blob/main/src/godzilla/market_data/calendar.py"
click node_instruments "https://github.com/vijish18/godzilla/blob/main/src/godzilla/market_data/instruments.py"
click node_universe "https://github.com/vijish18/godzilla/blob/main/src/godzilla/universe/builder.py"
click node_market_data "https://github.com/vijish18/godzilla/blob/main/src/godzilla/market_data/service.py"
click node_quality "https://github.com/vijish18/godzilla/blob/main/src/godzilla/market_data/quality.py"
click node_features "https://github.com/vijish18/godzilla/blob/main/src/godzilla/features/engine.py"
click node_feature_service "https://github.com/vijish18/godzilla/blob/main/src/godzilla/features/service.py"
click node_state_router "https://github.com/vijish18/godzilla/blob/main/src/godzilla/market_state/router.py"
click node_momentum "https://github.com/vijish18/godzilla/blob/main/src/godzilla/alphas/momentum_research.py"
click node_pairs "https://github.com/vijish18/godzilla/blob/main/src/godzilla/alphas/pairs_engine.py"
click node_other_alphas "https://github.com/vijish18/godzilla/tree/main/src/godzilla/alphas"
click node_ensemble "https://github.com/vijish18/godzilla/blob/main/src/godzilla/ensemble/normalize.py"
click node_allocator "https://github.com/vijish18/godzilla/blob/main/src/godzilla/portfolio/allocator.py"
click node_event_journal "https://github.com/vijish18/godzilla/blob/main/src/godzilla/core/events/journal.py"
click node_event_replay "https://github.com/vijish18/godzilla/blob/main/src/godzilla/core/events/replay.py"
click node_postgres "https://github.com/vijish18/godzilla/blob/main/src/godzilla/storage/postgres.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_calendar,node_instruments,node_universe,node_market_data,node_quality toneBlue
class node_features,node_feature_service,node_state_router,node_momentum,node_pairs,node_other_alphas toneAmber
class node_ensemble,node_allocator toneMint
class node_cli,node_configuration,node_compliance toneRose
class node_event_journal,node_event_replay,node_postgres,node_operator toneIndigo
```

## Components

### Market Inputs

- [NSE Calendar](https://github.com/vijish18/godzilla/blob/main/src/godzilla/market_data/calendar.py): `src/godzilla/market_data/calendar.py`
- [Instrument Master](https://github.com/vijish18/godzilla/blob/main/src/godzilla/market_data/instruments.py): `src/godzilla/market_data/instruments.py`
- [Universe Builder](https://github.com/vijish18/godzilla/blob/main/src/godzilla/universe/builder.py): `src/godzilla/universe/builder.py`
- [Market Data Service](https://github.com/vijish18/godzilla/blob/main/src/godzilla/market_data/service.py): `src/godzilla/market_data/service.py`
- [Data Quality](https://github.com/vijish18/godzilla/blob/main/src/godzilla/market_data/quality.py): `src/godzilla/market_data/quality.py`

### Features and Signals

- [Feature Engine](https://github.com/vijish18/godzilla/blob/main/src/godzilla/features/engine.py): `src/godzilla/features/engine.py`
- [Feature Publication](https://github.com/vijish18/godzilla/blob/main/src/godzilla/features/service.py): `src/godzilla/features/service.py`
- [Market-State Router](https://github.com/vijish18/godzilla/blob/main/src/godzilla/market_state/router.py): `src/godzilla/market_state/router.py`
- [Momentum Alpha](https://github.com/vijish18/godzilla/blob/main/src/godzilla/alphas/momentum_research.py): `src/godzilla/alphas/momentum_research.py`
- [Pairs Research](https://github.com/vijish18/godzilla/blob/main/src/godzilla/alphas/pairs_engine.py): `src/godzilla/alphas/pairs_engine.py`
- [Other Alpha Strategies](https://github.com/vijish18/godzilla/tree/main/src/godzilla/alphas): `src/godzilla/alphas`

### Alpha Allocation

- [Alpha Ensemble](https://github.com/vijish18/godzilla/blob/main/src/godzilla/ensemble/normalize.py): `src/godzilla/ensemble/normalize.py`
- [Portfolio Allocator](https://github.com/vijish18/godzilla/blob/main/src/godzilla/portfolio/allocator.py): `src/godzilla/portfolio/allocator.py`

### Operations

- [CLI](https://github.com/vijish18/godzilla/blob/main/src/godzilla/app/cli.py): `src/godzilla/app/cli.py`
- [Configuration](https://github.com/vijish18/godzilla/blob/main/src/godzilla/config/loader.py): `src/godzilla/config/loader.py`
- [Compliance Profiles](https://github.com/vijish18/godzilla/blob/main/src/godzilla/compliance/service.py): `src/godzilla/compliance/service.py`

### Events and Storage

- [Event Journal](https://github.com/vijish18/godzilla/blob/main/src/godzilla/core/events/journal.py): `src/godzilla/core/events/journal.py`
- [Event Replay](https://github.com/vijish18/godzilla/blob/main/src/godzilla/core/events/replay.py): `src/godzilla/core/events/replay.py`
- [PostgreSQL Storage](https://github.com/vijish18/godzilla/blob/main/src/godzilla/storage/postgres.py): `src/godzilla/storage/postgres.py`

### Other components

- **Operator**

## Connections

- Operator → CLI: invokes (evidence: `src/godzilla/app/cli.py`)
- CLI → Configuration: loads (evidence: `src/godzilla/app/cli.py`)
- CLI → Compliance Profiles: validates (evidence: `src/godzilla/app/cli.py`)
- CLI → Instrument Master: loads (evidence: `src/godzilla/app/cli.py`)
- CLI → Universe Builder: builds (evidence: `src/godzilla/app/cli.py`)
- Universe Builder → Instrument Master: uses (evidence: `src/godzilla/universe/builder.py`)
- Market Data Service → Data Quality: checks observations (evidence: `src/godzilla/market_data/service.py`)
- Market Data Service → NSE Calendar: uses sessions
- Market Data Service → Feature Engine: provides observations (evidence: `README.md`)
- Feature Engine → Market-State Router: provides features (evidence: `README.md`)
- Feature Engine → NSE Calendar: uses sessions (evidence: `src/godzilla/features/engine.py`)
- Feature Publication → Event Journal: publishes events (evidence: `src/godzilla/features/service.py`)
- Market-State Router → Momentum Alpha: routes permissions (evidence: `src/godzilla/alphas/momentum_research.py`)
- Market-State Router → Pairs Research: supplies state (evidence: `src/godzilla/alphas/pairs_engine.py`)
- Market-State Router → Other Alpha Strategies: routes permissions (evidence: `README.md`)
- Feature Engine → Momentum Alpha: supplies features (evidence: `src/godzilla/alphas/momentum_research.py`)
- Feature Engine → Pairs Research: supplies features (evidence: `src/godzilla/alphas/pairs_engine.py`)
- Momentum Alpha → Alpha Ensemble: supplies candidates (evidence: `README.md`)
- Pairs Research → Alpha Ensemble: supplies candidates (evidence: `README.md`)
- Other Alpha Strategies → Alpha Ensemble: supplies candidates (evidence: `README.md`)
- Alpha Ensemble → Portfolio Allocator: provides decisions (evidence: `README.md`)
- Portfolio Allocator → Event Journal: publishes decisions
- Market Data Service → Event Journal: records events (evidence: `README.md`)
- Event Journal → PostgreSQL Storage: persists through (evidence: `src/godzilla/core/events/journal.py`)
- Event Replay → Event Journal: replays events (evidence: `README.md`)
