# mahmoud-mh/macropulse architecture

> Architecture diagram of the GitHub repository mahmoud-mh/macropulse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahmoud-mh/macropulse
- Repository: https://github.com/mahmoud-mh/macropulse

## Overview

##### Project type and purpose
- MacroPulse is a full-stack web application:
- React/Vite frontend (SPA for task and indicator management)
- Django REST API backend (monolithic Django project with multiple apps)
- Celery + Redis for background task processing
- PostgreSQL as the primary data store
- Django Channels (WebSocket) for real-time updates
- External integration with FRED API

##### File structure
- Top‐level:
- frontend/ – React app (TypeScript, Vite)
- macro_pulse/ – Django project (settings, routing, ASGI/WGI, Celery config)
- authentication/, indicators/, websocket/ – Django “apps” implementing auth, indicator logic, real-time channels
- manage.py, Dockerfile, docker-compose.yml – orchestration & deployment
- requirements.txt – backend dependencies
- Patterns & roles:
- authentication/ – JWT auth, middleware, token store
- indicators/ – FRED API integration, data models, serializers, Celery tasks, admin templates
- websocket/ + macro_pulse/consumers.py + routing.py – Channels routing for live updates
- celery tasks & beat under indicators/ and macro_pulse/celery.py

##### Insights from README
- Clearly separates Frontend vs. Backend responsibility
- Backend features: Task Manager, Indicator Service, Auth System, WebSocket Service

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    User["User (Browser)"]:::external
    React["React SPA (frontend/src)"]:::frontend
    User -->|interacts with| React

    %% API Layer
    React -->|HTTP/HTTPS| DjangoAPI["Django REST API<br/>(macro_pulse/urls.py)"]:::api

    %% Django Monolith
    subgraph "Django Monolith"
        direction TB
        Auth["Authentication Service<br/>(authentication/)"]:::api
        Indicators["Indicator Service<br/>(indicators/)"]:::api
        Channels["WebSocket Service<br/>(macro_pulse/asgi.py)"]:::realtime
        CeleryWB["Celery Worker & Beat<br/>(macro_pulse/celery.py)"]:::jobs
    end

    %% Data Stores
    PostgreSQL["PostgreSQL"]:::db-orange
    Redis["Redis"]:::db-purple

    %% External & Monitoring
    FRED["External FRED API"]:::external
    Flower["Flower Monitoring UI"]:::monitor

    %% Connections
    DjangoAPI -->|routes to| Auth
    DjangoAPI -->|routes to| Indicators
    DjangoAPI -->|routes to| Channels
    DjangoAPI -->|reads/writes| PostgreSQL
    DjangoAPI -->|enqueues tasks| Redis

    CeleryWB -->|fetches tasks from| Redis
    CeleryWB -->|calls| FRED
    CeleryWB -->|updates| PostgreSQL
    CeleryWB -->|emits events to| Channels

    Indicators -->|uses| FRED
    Indicators -->|defines tasks in| CeleryWB

    Channels -->|pushes updates to| React
    Channels -->|subscribes via| Redis

    CeleryWB -->|schedules via| Redis

    Flower -->|monitors| Redis
    Flower -->|monitors| CeleryWB

    %% Click Events
    click React "https://github.com/mahmoud-mh/macropulse/tree/main/frontend/"
    click DjangoAPI "https://github.com/mahmoud-mh/macropulse/blob/main/macro_pulse/urls.py"
    click Auth "https://github.com/mahmoud-mh/macropulse/tree/main/authentication/"
    click Indicators "https://github.com/mahmoud-mh/macropulse/tree/main/indicators/"
    click Channels "https://github.com/mahmoud-mh/macropulse/blob/main/macro_pulse/asgi.py"
    click CeleryWB "https://github.com/mahmoud-mh/macropulse/blob/main/macro_pulse/celery.py"
    click FRED "https://github.com/mahmoud-mh/macropulse/blob/main/indicators/fred_api.py"
    click Flower "https://github.com/mahmoud-mh/macropulse/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,color:#000
    classDef api fill:#90EE90,stroke:#000,color:#000
    classDef db-orange fill:#FFA500,stroke:#000,color:#000
    classDef db-purple fill:#9370DB,stroke:#000,color:#000
    classDef jobs fill:#FFFF66,stroke:#000,color:#000
    classDef realtime fill:#20B2AA,stroke:#000,color:#000
    classDef external fill:#D3D3D3,stroke:#000,color:#000
    classDef monitor fill:#FFB6C1,stroke:#000,color:#000
```
