# sks006/halal-equity-catalyst architecture

> Architecture diagram of the GitHub repository sks006/halal-equity-catalyst, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sks006/halal-equity-catalyst
- Repository: https://github.com/sks006/halal-equity-catalyst

## Overview

Equity Catalyst is a Solana spot-liquidity and portfolio-rebalancing platform with Shariah screening, policy-controlled execution, vaults, and Meteora bonding-curve price discovery. The principal workflow is market/event observation → policy and risk evaluation → proposal validation and simulation → isolated signing and on-chain execution → audit/state recording. The README documents these stages and major capabilities; sampled source confirms key execution, stream-management, SDK, and worker boundaries, but not all route-to-service wiring.

Main entry points: [`apps/api/src/services/execution_engine_service.rs`](https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/services/execution_engine_service.rs) (Execution Service), [`apps/api/src/routes`](https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/routes) (API Routes), [`apps/api/src/workers/policy_worker.rs`](https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/workers/policy_worker.rs) (Policy Worker), [`apps/api/src/engines/decision_engine`](https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/engines/decision_engine) (Decision Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web and SDK"]
  node_web["Web Application"]
  node_webapi["Web API Client<br/>[api-client.ts]"]
  node_sdk["TypeScript SDK<br/>[client.ts]"]
end

subgraph group_api["API and Workers"]
  node_router["HTTP Router<br/>[router.rs]"]
  node_routes["API Routes"]
  node_policyworker["Policy Worker<br/>[policy_worker.rs]"]
  node_execution["Execution Service"]
  node_oracle["Oracle Service<br/>[oracle_service.rs]"]
end

subgraph group_domain["Policy and Trading"]
  node_dbc["DBC Engine"]
  node_policy["Policy Engine"]
  node_decision["Decision Engine"]
  node_risk["Risk Engine"]
  node_screening["Shariah Screening"]
  node_signer["Signing Pipeline<br/>[pipeline.rs]"]
end

subgraph group_chain["Solana and Providers"]
  node_vaultprogram["Equity Vault Program<br/>[lib.rs]"]
  node_pyth["Pyth Feeds<br/>[manager.rs]"]
  node_solana["Solana Service<br/>[solana_service.rs]"]
  node_jupiter["Jupiter Integration<br/>[client.rs]"]
  node_meteora["Meteora DBC SDK<br/>[service.ts]"]
end

subgraph group_state["Persistence"]
  node_postgres[("PostgreSQL")]
  node_redis["Redis Queue"]
end

node_user(("Investor or Operator"))
node_solanacluster(("Solana Cluster"))
node_pythservice(("Pyth Network"))
node_jupiterprovider(("Jupiter Provider"))
node_meteoraprovider(("Meteora DBC"))

node_user -->|"uses"| node_web
node_web -->|"requests data"| node_webapi
node_webapi -->|"calls API"| node_routes
node_sdk -.->|"calls API"| node_routes
node_sdk -.->|"reads chain"| node_solanacluster
node_router -->|"dispatches"| node_routes
node_routes -->|"requests prices"| node_oracle
node_routes -->|"requests simulation"| node_dbc
node_policyworker -->|"consumes events"| node_redis
node_policyworker -->|"loads and records"| node_postgres
node_policyworker -->|"evaluates event"| node_decision
node_decision -->|"checks rules"| node_policy
node_decision -->|"checks risk"| node_risk
node_policy -->|"checks eligibility"| node_screening
node_execution -->|"revalidates trade"| node_risk
node_execution -->|"checks prices"| node_oracle
node_execution -->|"simulates trade"| node_dbc
node_execution -->|"requests signature"| node_signer
node_execution -->|"executes action"| node_solana
node_execution -->|"records execution"| node_postgres
node_signer -->|"submits signed transaction"| node_solana
node_solana -->|"reads and submits"| node_solanacluster
node_oracle -->|"normalizes prices"| node_pyth
node_pyth -->|"streams prices"| node_pythservice
node_routes -.->|"requests quotes"| node_jupiter
node_jupiter -->|"fetches quote or swap"| node_jupiterprovider
node_vaultprogram -->|"executes on-chain"| node_solanacluster
node_meteora -.->|"creates pools and swaps"| node_meteoraprovider

click node_web "https://github.com/sks006/halal-equity-catalyst/tree/main/apps/web/src/app"
click node_webapi "https://github.com/sks006/halal-equity-catalyst/blob/main/apps/web/src/lib/api-client.ts"
click node_sdk "https://github.com/sks006/halal-equity-catalyst/blob/main/sdk/src/client.ts"
click node_router "https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/router.rs"
click node_routes "https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/routes"
click node_policyworker "https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/workers/policy_worker.rs"
click node_execution "https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/services/execution_engine_service.rs"
click node_oracle "https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/services/oracle_service.rs"
click node_dbc "https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/engines/dbc_engine"
click node_policy "https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/engines/policy_engine"
click node_decision "https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/engines/decision_engine"
click node_risk "https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/engines/risk_engine"
click node_screening "https://github.com/sks006/halal-equity-catalyst/tree/main/crates/shared/src/shariah"
click node_signer "https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/engines/execution_signer/pipeline.rs"
click node_vaultprogram "https://github.com/sks006/halal-equity-catalyst/blob/main/programs/equity_vault/src/lib.rs"
click node_pyth "https://github.com/sks006/halal-equity-catalyst/blob/main/integrations/pyth/manager.rs"
click node_solana "https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/services/solana_service.rs"
click node_jupiter "https://github.com/sks006/halal-equity-catalyst/blob/main/integrations/jupiter/client.rs"
click node_meteora "https://github.com/sks006/halal-equity-catalyst/blob/main/sdk/src/meteora/service.ts"
click node_postgres "https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/repositories"

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_web,node_webapi,node_sdk toneBlue
class node_router,node_routes,node_policyworker,node_execution,node_oracle toneAmber
class node_dbc,node_policy,node_decision,node_risk,node_screening,node_signer toneMint
class node_vaultprogram,node_pyth,node_solana,node_jupiter,node_meteora toneRose
class node_postgres,node_redis,node_user,node_solanacluster,node_pythservice,node_jupiterprovider,node_meteoraprovider toneIndigo
```

## Components

### Web and SDK

- [Web Application](https://github.com/sks006/halal-equity-catalyst/tree/main/apps/web/src/app): `apps/web/src/app`
- [Web API Client](https://github.com/sks006/halal-equity-catalyst/blob/main/apps/web/src/lib/api-client.ts): `apps/web/src/lib/api-client.ts`
- [TypeScript SDK](https://github.com/sks006/halal-equity-catalyst/blob/main/sdk/src/client.ts): `sdk/src/client.ts`

### API and Workers

- [HTTP Router](https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/router.rs): `apps/api/src/router.rs`
- [API Routes](https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/routes): `apps/api/src/routes`
- [Policy Worker](https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/workers/policy_worker.rs): `apps/api/src/workers/policy_worker.rs`
- [Execution Service](https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/services/execution_engine_service.rs): `apps/api/src/services/execution_engine_service.rs`
- [Oracle Service](https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/services/oracle_service.rs): `apps/api/src/services/oracle_service.rs`

### Policy and Trading

- [DBC Engine](https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/engines/dbc_engine): `apps/api/src/engines/dbc_engine`
- [Policy Engine](https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/engines/policy_engine): `apps/api/src/engines/policy_engine`
- [Decision Engine](https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/engines/decision_engine): `apps/api/src/engines/decision_engine`
- [Risk Engine](https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/engines/risk_engine): `apps/api/src/engines/risk_engine`
- [Shariah Screening](https://github.com/sks006/halal-equity-catalyst/tree/main/crates/shared/src/shariah): `crates/shared/src/shariah`
- [Signing Pipeline](https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/engines/execution_signer/pipeline.rs): `apps/api/src/engines/execution_signer/pipeline.rs`

### Solana and Providers

- [Equity Vault Program](https://github.com/sks006/halal-equity-catalyst/blob/main/programs/equity_vault/src/lib.rs): `programs/equity_vault/src/lib.rs`
- [Pyth Feeds](https://github.com/sks006/halal-equity-catalyst/blob/main/integrations/pyth/manager.rs): `integrations/pyth/manager.rs`
- [Solana Service](https://github.com/sks006/halal-equity-catalyst/blob/main/apps/api/src/services/solana_service.rs): `apps/api/src/services/solana_service.rs`
- [Jupiter Integration](https://github.com/sks006/halal-equity-catalyst/blob/main/integrations/jupiter/client.rs): `integrations/jupiter/client.rs`
- [Meteora DBC SDK](https://github.com/sks006/halal-equity-catalyst/blob/main/sdk/src/meteora/service.ts): `sdk/src/meteora/service.ts`

### Persistence

- [PostgreSQL](https://github.com/sks006/halal-equity-catalyst/tree/main/apps/api/src/repositories): `apps/api/src/repositories`
- **Redis Queue**

### Other components

- **Investor or Operator**
- **Solana Cluster**
- **Pyth Network**
- **Jupiter Provider**
- **Meteora DBC**

## Connections

- Investor or Operator → Web Application: uses
- Web Application → Web API Client: requests data
- Web API Client → API Routes: calls API
- TypeScript SDK → API Routes: calls API
- TypeScript SDK → Solana Cluster: reads chain
- HTTP Router → API Routes: dispatches
- API Routes → Oracle Service: requests prices
- API Routes → DBC Engine: requests simulation
- Policy Worker → Redis Queue: consumes events
- Policy Worker → PostgreSQL: loads and records
- Policy Worker → Decision Engine: evaluates event
- Decision Engine → Policy Engine: checks rules
- Decision Engine → Risk Engine: checks risk
- Policy Engine → Shariah Screening: checks eligibility
- Execution Service → Risk Engine: revalidates trade
- Execution Service → Oracle Service: checks prices
- Execution Service → DBC Engine: simulates trade
- Execution Service → Signing Pipeline: requests signature
- Execution Service → Solana Service: executes action
- Execution Service → PostgreSQL: records execution
- Signing Pipeline → Solana Service: submits signed transaction
- Solana Service → Solana Cluster: reads and submits
- Oracle Service → Pyth Feeds: normalizes prices
- Pyth Feeds → Pyth Network: streams prices
- API Routes → Jupiter Integration: requests quotes
- Jupiter Integration → Jupiter Provider: fetches quote or swap
- Equity Vault Program → Solana Cluster: executes on-chain
- Meteora DBC SDK → Meteora DBC: creates pools and swaps