Fluence

The Intelligent Developer Flow Engine

Track your invisible work. Prove your flow. Own your narrative.

Fluence dynamically measures, visualizes, and optimizes your developer flow state through adaptive learning.

🌊 What is Fluence?

Fluence is a local desktop agent that tracks your digital footprint across Git, Jira, Slack, Calendar, ChatGPT, and your IDE — then computes a dynamic Adaptive Flow State Score using Bayesian Networks. It visualizes everything through a beautiful local Electron desktop app and a comprehensive Grafana dashboard.

Instead of counting raw hours, Fluence understands context switching, deep work quality, and sustainable rhythms to prove the value of your invisible work.

---

✨ Core Features

#	Feature	Description
1	Adaptive Flow State Score	Calculates your flow (0–100) dynamically using Consistency, Deep Work, Low Switches, Productive Time, and Adaptive Learning weights.
2	Interactive Flow Scenarios	Simulate how 4 developer habits (e.g., Consistent Worker vs. Procrastinator) empirically impact flow state over a 10-day deadline.
3	Premium Desktop Dashboard	Stunning glassmorphic UI built in Vanilla CSS + Electron to monitor metrics in real-time.
4	Cross-Tool Task Correlation	Regex + fuzzy NLP matching groups events from 8 tools into unified task clusters.
5	Predictive Flow Disruption Alerts	8 alert types (calendar lookahead, historical patterns) with targeted desktop notifications.
6	Invisible Work Quantifier	Accountability reports + freelancer invoice generation from automated tracked activity.
7	Developer Activity Network Graph	Temporal directed graph (NetworkX) with centrality metrics, rendered in Grafana.

---

🧮 Flow Score is DYNAMIC — Not Static

The flow score in Fluence uses dynamic, adaptive weighting rather than purely manual/static weights. It learns which signals matter most for your productivity patterns over time.

Weighting Architecture

%%{init: {"look": "handDrawn", "theme": "light"}}%%
flowchart TD
    A[Raw Signals from 8 Tools] --> B[SignalCalculator]
    B --> C[Normalize via per-user history]
    C --> D[BayesianWeightEngine]
    D --> E[Weighted Sum → Flow Score 0-100]

    D --> F[Daily Nightly Recalibration]
    F --> G[Mutual Info between signals & proxy labels]
    G --> H[EMA smoothing α=0.3]
    H --> I[(Updated weights saved to SQLite DB)]

Loading

The 6 Core Signals Being Weighed

1. csf — Context Switch Frequency
2. tci — Task Continuity Index
3. dd — Deep Work Duration
4. ir — Interrupt Recovery Time
5. ibp — Idle/Break Pattern
6. aiu — AI Tool Usage Relevance (e.g., ChatGPT integration)

Weight Learning Process

1. Nightly Recalibration (recalibrate_daily()):
   • Looks back 14 days (BAYESIAN_LOOKBACK_DAYS)
   • Requires a minimum of 7 samples (BAYESIAN_MIN_SAMPLES)
2. Proxy Labels Generated from:
   • Coding time (weight=0.4) — positive
   • Deep work time (weight=0.3) — positive
   • Context switches (weight=0.15) — negative
   • Meeting time (weight=0.15) — negative
3. Mutual Information (MI) is then computed between each of the 6 signals and these proxy productivity labels.
4. EMA Smoothing (_update_weights_ema()):
   • Adapts the neural weights smoothly to avoid erratic jumps using Exponential Moving Average:
   • new_w = α * mi_w + (1 - α) * old_w
   • Learning rate (α) = 0.3 (BAYESIAN_LEARNING_RATE)

Note: In the event of zero historical data, a uniform /6 fallback weight is applied until your true patterns emerge. There is no manual overriding API; Fluence is designed to learn from your actual tracked work.

---

🏗️ Architecture

%%{init: {"look": "handDrawn", "theme": "light"}}%%
flowchart TD
    subgraph E[ELECTRON SHELL]
        direction LR
        FG[Flow Scenarios & Gauge]
        AP[Alerts Dashboard]
        SI[Settings & Integrations]
    end

    subgraph P[PYTHON ENGINE]
        direction TB
        subgraph Col[COLLECTORS]
            direction LR
            C1(GitHub) & C2(Jira) & C3(Slack) & C4(Calendar) & C5(IDE) & C6(Window) & C7(Idle) & C8(ChatGPT)
        end

        subgraph Proc[PROCESSORS]
            direction TB
            N(Normalizer) --> T(Task Correlator)
            T --> S(Signal Calculator)
            S --> B(Bayesian Adaptor)
            B --> F(Flow Score Engine)
            F --> Pred(Prediction Engine)
            Pred --> G(Graph Builder)
            G --> R(Reports System)
        end

        subgraph Rep[REPORTERS]
            direction LR
            AR[Accountability] & IG[Invoice Gen]
        end

        Col --> Proc
        Proc --> Rep
    end

    subgraph DB[STORAGE & DISPLAY]
        direction LR
        SQL[(SQLite DB)] <--> GRAF[Grafana Dashboard<br/>10 Panels in Docker]
    end

    E <-->|IPC commands & JSON Data| P
    P <--> DB

Loading

---

🚀 Quick Start

Prerequisites

• Python 3.11+ with pip
• Node.js 18+ with npm
• Docker (for Grafana)
• Windows 10/11 (OS-level collectors use pywin32 / ctypes)

1. Clone & Install Python Dependencies

git clone https://github.com/SreeAditya-Dev/VORTEX-2.0.git
cd VORTEX-2.0
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env with your API keys (GitHub, Jira, Slack, Google Calendar)
# Set MODE=mock for demo data, MODE=live for real APIs

3. Seed Demo Data (Optional)

python scripts/seed_events.py
python scripts/seed_dashboard.py

4. Start Grafana Dashboard

docker-compose up -d
# Dashboard available at http://localhost:3000
# Default login: admin / vortex2024

5. Start Electron Desktop App (Primary UI)

cd electron
npm install
npm start

Note: The Electron app automatically spins up the local Python IPC tracking server in the background.

6. Start Engine Only (Headless)

python -m engine.main --mock

---

📊 Grafana Dashboard Panels

#	Panel	Type	Description
1	🔥 Current Flow Score	Stat Gauge	Real-time score 0-100, color-coded
2	📈 Flow Score Timeline	Timeseries	24h trend with threshold lines
3	🥧 Time Allocation	Donut Pie	Activity distribution breakdown
4	🔥 Context Switch Heatmap	Heatmap	Hour × Day-of-week switch density
5	🔗 Task Correlation Flow	State Timeline	Tool → Task flow visualization
6	⚖️ Bayesian Weight Evolution	Timeseries	Signal weight adaptation over time
7	🏋️ Deep Work Streaks	Bar Chart	Daily deep work duration
8	📋 Weekly Accountability	Table	Full metrics with cell gauges
9	🌐 Activity Network Graph	Node Graph	Developer activity network
10	🔔 Active Alerts	Table	Flow disruption predictions

---

🗂️ Project Structure

VORTEX-2.0/
├── engine/
│   ├── main.py               # Orchestrator (APScheduler)
│   ├── config.py             # Centralized configuration
│   ├── database.py           # SQLite schema & CRUD
│   ├── models.py             # Typed dataclass models
│   ├── collectors/           # 8 data source collectors
│   │   ├── github_collector.py
│   │   ├── jira_collector.py
│   │   ├── slack_collector.py
│   │   ├── calendar_collector.py
│   │   ├── ide_collector.py
│   │   ├── os_window_watcher.py
│   │   ├── idle_detector.py
│   │   └── chatgpt_detector.py
│   ├── processors/           # Intelligence pipeline
│   │   ├── event_normalizer.py
│   │   ├── task_correlator.py
│   │   ├── signal_calculator.py
│   │   ├── bayesian_engine.py
│   │   ├── flow_score.py
│   │   ├── prediction_engine.py
│   │   ├── graph_builder.py
│   │   └── accountability_report.py
│   └── reporters/
│       └── invoice_generator.py
├── electron/
│   ├── main.js               # Electron main process
│   ├── preload.js            # IPC bridge (contextBridge)
│   └── renderer/
│       ├── index.html        # App Layout
│       ├── app.js            # Frontend Routing & Scenario Data
│       ├── styles.css        # Premium UI Design System
│       └── icon.png          # App Logo
├── grafana/
│   ├── dashboards/shadow-work.json
│   └── provisioning/
├── scripts/
│   ├── seed_events.py
│   └── seed_dashboard.py
├── tests/                    # Unit tests for processors
├── docker-compose.yml
└── requirements.txt

---

🧪 Running Tests

python -m pytest tests/ -v

---

🔧 Configuration

All settings live in engine/config.py and can be overridden via environment variables:

Variable	Default	Description
MODE	mock	mock for demo data, live for real APIs
GITHUB_TOKEN	—	GitHub Personal Access Token
JIRA_URL	—	Jira instance URL
SLACK_TOKEN	—	Slack Bot OAuth Token
POLL_INTERVAL	30	Collector polling interval (seconds)
PYTHON_PATH	python	Path to Python executable

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built for developers who value deep work.