Skip to content

singhsum/flux

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

37 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Flux

Flux — Engineering Intelligence

The AI-Native Engineering Intelligence Platform

From messy codebases to instant clarity — for MSPs, dev teams, and the engineers who keep everything running.

MIT Licence Python 3.10+ Node 20+ Open Source ANZ Data Sovereign



Overview

AI Intelligence

Flux — Engineering Intelligence is a unified AI platform that replaces the fragmented collection of individual AI subscriptions with a single, secure, monitored environment.

Think of it as your organisation's own private AI hub — with the models you trust, the governance your security team requires, and the engineering-specific intelligence your developers need.



4–6
AI tools the average developer juggles today

$200+
Monthly AI tool spend per developer (unmanaged)

73%
Enterprises with no AI usage governance policy

0
Native audit trails in tools like ChatGPT or Cursor

The Problem

Problem

Engineering Teams Are Flying Blind with AI

Individual AI tools are powerful — but used in isolation, without governance, without codebase context, and without a unified commercial model, they create more chaos than value at enterprise scale.


Tool Sprawl & Budget Leakage
Developers subscribe to Cursor, ChatGPT Plus, GitHub Copilot, and Claude individually. No central visibility into total spend, no ability to rationalise, and no way to enforce usage policies. A 50-person engineering team easily spends $8,000–$12,000/month across fragmented AI subscriptions.
No Codebase Memory
General AI tools know nothing about your architecture, naming conventions, or past incidents. Every conversation starts from zero. Developers re-explain the entire context every session — burning time and getting lower-quality answers than a tool that truly knows the codebase.
Zero Governance or Audit Trail
Who on your team asked an AI to write that authentication module? There is no answer today — and for SOC 2, ISO 27001, or APRA-regulated organisations, this is a growing liability. AI usage is completely invisible to compliance teams.
Data Sovereignty Risk
Free and pro-tier plans on public tools may use prompts for model training. For companies with proprietary IP, pasting source code into consumer AI tools is an unmanaged data leakage risk with no data residency guarantee.
Unpredictable & Uncapped Costs
Consumption APIs have no ceiling. A single developer can run a runaway agent job and generate thousands of dollars in API costs overnight — with no approval gate and no way to predict month-end spend.
Vendor Lock-in Without Leverage
Building your dev workflow on a single AI provider means their pricing changes are your cost changes. API prices can change overnight — Anthropic, OpenAI, and Microsoft all changed terms in 2024. No ability to swap models, no resilience, no migration path.

💡 Studies estimate developers spend 2–3 hours per week context-switching between AI tools and re-explaining their codebase. At a fully-loaded cost of $80–$120/hour, that's $640–$1,440 of wasted productivity per developer per month.


The Solution

Solution

One Secure Platform. Every AI Capability Your Team Needs.

Flux — Engineering Intelligence replaces tool sprawl with a single governed environment — combining deep engineering intelligence with general-purpose AI access, agent orchestration, and enterprise-grade security.


Platform Architecture

┌─────────────────────────────────────────────────────────────────┐
│                  Flux — Engineering Intelligence                 │
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐  │
│  │   🔍 Ask Flux    │  │  🌐 Secure AI Hub │  │ 🤖 SDLC Agents│  │
│  │                  │  │                  │  │               │  │
│  │ Codebase Q&A     │  │ ChatGPT          │  │ Researcher    │  │
│  │ iTroubleshooting │  │ Claude           │  │ Product Owner │  │
│  │ Architecture     │  │ Gemini           │  │ Developer     │  │
│  │   Diagrams       │  │ Ollama (local)   │  │ Tech Lead     │  │
│  │ Auto Docs        │  │ AI Council       │  │ Tester        │  │
│  │ Test Generation  │  │ Agent Builder    │  │               │  │
│  └──────────────────┘  └──────────────────┘  └───────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Security & Governance Layer                  │   │
│  │  Full Audit Trail · SSO (SAML/LDAP/OIDC) · IC Budgets   │   │
│  │  Data Residency Choice · Role-Based Access · ANZ Compliant│   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                   Data & Intelligence Layer               │   │
│  │  Postgres + pgvector · Codebase Index · Meilisearch      │   │
│  │  Git/ZIP Ingestion · Confluence · Jira · Local Files     │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

🔍 Ask Flux — Engineering Intelligence

An AI layer permanently indexed to your codebase. Ask natural language questions about your architecture. Get AI-generated documentation, Mermaid diagrams, unit tests, and troubleshooting analysis — all grounded in your actual code, not generic knowledge.

  • Codebase Q&A — natural-language answers grounded in your real code and documentation
  • iTroubleshooting — paste incident + logs → structured triage with hypotheses and file citations
  • Architecture diagrams — auto-generate as-built Mermaid maps: dependencies, flows, class diagrams
  • Auto documentation — generate README, API docs, and architecture docs from source code
  • Test generation — one-click unit tests for any indexed file

🌐 Secure AI Hub — General Intelligence

Access ChatGPT, Claude, Gemini, or your own Ollama instance from a single monitored interface. Build and share agents within your organisation. Use AI Council to query multiple models simultaneously.

  • Multi-model secure chat — OpenAI, Anthropic, Google, local Ollama
  • AI Council — parallel multi-model queries, side-by-side comparison (unique in the market, fully audited)
  • Org-wide agent builder and agent sharing
  • Project context injection for any AI research session

🤖 SDLC Agent Team — Autonomous Dev

A coordinated team of AI agents handling the full development lifecycle — structured, auditable, and interruptable at every handoff.

Researcher → Product Owner → Developer → Tech Lead → Tester

Multi-agent orchestration, autonomous feature development, test coverage, PR creation.


Features

Feature
Current

EI MVP
Ask Flux — codebase Q&A
iTroubleshooting (log triage & resolution)
Auto documentation generation
Architecture diagrams (Mermaid)
Unit test generation
AI chat hub (FluxChat, multi-model)
Multi-LLM support (OpenAI, Anthropic, Ollama)
SDLC agent team (full dev lifecycle)
Secure hub: ChatGPT, Claude, Gemini in one UI
AI Agent builder + org-wide agent sharing
AI Council (parallel multi-model queries)
Project context injection for AI research
Multi-tenant SaaS platform
Enterprise SSO (SAML / LDAP / OIDC)

5 capabilities shipping today · 14 in the proposed MVP


Who Benefits

Teams

Built for Teams Who Can't Afford Downtime


👩‍💻 Individual Developer

  • One tool that knows the codebase permanently
  • AI generates tests, diagrams, and docs on demand
  • Access to GPT-4o and Claude without separate subscriptions
  • No more re-explaining architecture every session

🧑‍💼 Engineering Manager

  • Codebase knowledge stays in the platform, not in people's heads
  • Usage dashboards show AI adoption and ROI
  • AI-generated test coverage reduces review burden
  • Context survives when developers leave

⚙️ CTO / VP Engineering

  • Single AI investment replaces 4–5 tools
  • Predictable per-user cost, no surprise bills
  • Architecture governance via AI-generated diagrams
  • SDLC agents accelerate roadmap delivery

🛡️ Security & Compliance

  • Immutable audit log of every AI interaction
  • Local LLM (Ollama/vLLM) option — code never leaves your network
  • SAML/LDAP/OIDC SSO with role-based access
  • Configurable data residency (SOC 2, ISO 27001, APRA CPS 234)

💰 CFO / Finance

  • Single invoice, predictable per-user pricing
  • Intelligence Credit caps eliminate surprise overages
  • Replaces $79+/dev/month in individual subscriptions

🏢 MSPs & L2/L3 Support Teams

  • Instant context on client codebases — no tribal knowledge required
  • AI-structured incident triage reduces MTTR from hours to minutes
  • Document complex environments at the click of a button
  • Sovereign AI: keep client IP and sensitive data on-shore

Why Not Just Claude, Cursor, or Copilot?

Differentiation

These are excellent tools. Flux — Engineering Intelligence is not a replacement — it is the governance, integration, and codebase-intelligence layer that makes them safe and scalable to use across an engineering organisation.


Vendor Lock-in Risk
API prices can change overnight — Anthropic, OpenAI, and Microsoft all changed terms in 2024. Flux — EI is multi-model by design. Swap providers without changing your workflow.


Zero Audit Trail
APRA CPS 234, ISO 27001, and SOC 2 require demonstrable AI controls. Ungoverned developer AI usage — where prompts and outputs are unlogged — fails every compliance audit automatically.


No Codebase Memory
Every Claude or Cursor session starts from zero. Flux — EI indexes your codebase permanently at the org level — context that persists, compounds, and doesn't leave when a developer does.

IP & Data Sovereignty
Free and pro-tier plans on public tools may use prompts for model training. Flux — EI with Ollama/vLLM keeps your IP strictly within your own network perimeter.


Cost Unpredictability
Consumption APIs have no ceiling. An overnight SDLC agent job can generate $500–$2K with no approval gate. Flux — EI's Intelligence Credit system gives every user a hard monthly budget they cannot exceed.


No Governance Layer
Individual subscriptions scattered across a team create shadow AI usage — invisible to security and leadership. Flux — EI provides org-wide visibility, usage controls, and a single pane of glass.


Cost comparison — 50 developers

Stack Monthly Cost Governance Codebase Memory Audit Trail
Cursor + Claude Pro + Copilot ~$3,950
Flux — EI Developer tier ~$1,450
Flux — EI Professional tier ~$4,950 ✅ + SSO + SLA

Get Started

Prerequisites

Requirement Version Notes
Python 3.10+ (3.12+ recommended) FastAPI backend
Node.js 20+ LTS Vite frontend
Git current Clone / updates
Docker (optional) current Production deploy, Postgres, Ollama

LLM access — pick at least one:

Provider Key Notes
Anthropic (Claude) ANTHROPIC_API_KEY Recommended
OpenAI OPENAI_API_KEY GPT-4o, GPT-4o-mini
Google AI Studio (Gemini) GOOGLE_API_KEY Flash, Pro
Azure OpenAI Keys + endpoint in .env ANZ region available
Ollama No key needed LLM_PROVIDER=ollama — fully local, data-sovereign

Quickstart — Local Dev

# 1. Clone
git clone <repository-url> flux && cd flux

# 2. Configure
cp backend/.env.example backend/.env
# Edit backend/.env — set at least one LLM API key

# 3. Start
chmod +x start.sh && ./start.sh
URL Service
http://localhost:5173 Frontend (Vite)
http://localhost:8000 API
http://localhost:8000/docs OpenAPI / Swagger
# Stop everything
./stop.sh

# Keep services running across restart
./stop.sh --keep-postgres
./stop.sh --keep-ollama

Running Options

Method Best for Frontend API Setup
./start.sh Dev, fast hot-reload :5173 :8000 ~2 min
Docker Compose Production, demos :8080 :8080/api ~5 min
Dev Container Team onboarding :5173 :8000 ~3 min

Docker — Minimal (SQLite)

docker compose up --build -d
# Open http://localhost:8080

Docker — Full Stack (Postgres + Ollama)

cp backend/.env.docker.example backend/.env
docker compose --profile deps up -d --build
docker exec -it flux-backend python scripts/apply_postgres_schema.py

Docker — With Secure AI Hub (FluxChat)

cp fluxchat.env.example fluxchat.env
# Edit fluxchat.env — set JWT_SECRET, JWT_REFRESH_SECRET, OIDC secrets

docker compose --profile fluxchat up -d
# Open http://localhost:8080 → General Chat

Full FluxChat docs: docs/FLUXCHAT.md

Dev Container (VS Code / Cursor)

  1. Open repo in VS Code or Cursor
  2. Cmd/Ctrl + Shift + PDev Containers: Reopen in Container
  3. Edit backend/.env, then ./start.sh

Manual Start (without start.sh)

# Terminal 1 — Backend
cd backend
python3 -m pip install -r requirements.txt
python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Terminal 2 — Frontend
cd frontend
npm install && npm run dev

Installation by OS

macOS
brew install python@3.12 node git
git clone <repo-url> flux && cd flux
cd backend && cp .env.example .env   # add your LLM key
cd .. && chmod +x start.sh && ./start.sh
Windows
winget install Python.Python.3.12 OpenJS.NodeJS.LTS Git.Git
# Then in Git Bash:
cd backend && cp .env.example .env
cd .. && ./start.sh

PowerShell alternative: use the Manual Start with py -m pip / py -m uvicorn.

Ubuntu / Debian
sudo apt update && sudo apt install -y python3 python3-pip python3-venv git curl
# Install Node 20+ via nvm:
nvm install 20 && nvm use 20

git clone <repo-url> flux && cd flux
cd backend && cp .env.example .env
cd .. && chmod +x start.sh && ./start.sh
PostgreSQL + pgvector (optional)
# Add to backend/.env
DATABASE_URL=postgresql://flux:flux@127.0.0.1:5432/flux

# Start Postgres container and apply schema
docker compose --profile deps up -d postgres
cd backend && python3 scripts/apply_postgres_schema.py

# Migrate existing SQLite data (if any)
python3 scripts/migrate_sqlite_to_postgres.py

Full guide: docs/POSTGRES_SETUP.md


Production Build — Frontend

# From the repository root
NODE_OPTIONS="--max-old-space-size=4096" npm run build --workspace=frontend

Note: If you encounter missing packages, run npm ci from the repository root first — this performs a clean install from package-lock.json and fixes any partial installs.


Environment Variables

Variable Local dev Docker Compose Dev Container
DATABASE_URL ...@127.0.0.1:5432/... ...@postgres:5432/... ...@host.docker.internal:5432/...
OLLAMA_BASE_URL http://127.0.0.1:11434 http://ollama:11434 http://host.docker.internal:11434
VITE_DEV_API_PROXY http://127.0.0.1:8000 http://127.0.0.1:8000

Ports Reference

Port Service
5173 Vite dev server (local / dev container)
8000 FastAPI backend (local / dev container)
8080 nginx (Docker production stack)
5432 PostgreSQL (profile deps)
11434 Ollama (profile deps)

Architecture

graph TB
    Browser["🌐 Browser"]

    subgraph FLUX ["Flux — Engineering Intelligence"]
        direction TB

        subgraph UI ["Frontend — React + Vite"]
            AskFlux["🔍 Ask Flux UI"]
            FluxChat["🌐 Secure AI Hub\n(FluxChat)"]
            SDLCUI["🤖 SDLC Agent UI"]
        end

        subgraph API ["Backend — FastAPI"]
            Ingest["📥 Ingest\n(Git / ZIP)"]
            ChatAPI["💬 Chat API"]
            DiagramAPI["📐 Diagram API"]
            DocsAPI["📄 Docs API"]
            TestAPI["🧪 Test API"]
            Orch["🎯 Orchestrator\n(SDLC Agents)"]
        end

        subgraph DATA ["Data Layer"]
            SQLite["🗄️ SQLite\n(default)"]
            PG["🐘 Postgres\n+ pgvector"]
            FS["📁 File Store\n(projects/)"]
            Meili["🔍 Meilisearch"]
        end
    end

    subgraph LLMs ["LLM Providers"]
        Claude["Anthropic\nClaude"]
        OAI["OpenAI\nGPT-4o"]
        Gemini["Google\nGemini"]
        Ollama["🏠 Ollama\n(local / on-prem)"]
    end

    subgraph Sources ["Code Sources"]
        GitHub["GitHub / GitLab"]
        ZIP["ZIP Upload"]
        Confluence["Confluence / Jira"]
        PDFs["Local PDFs / Docs"]
    end

    Browser --> UI
    UI --> API
    API --> DATA
    API --> LLMs
    Sources --> Ingest
    Ingest --> DATA
Loading

Project Structure

flux/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI entry point
│   │   ├── config.py            # Settings (reads .env)
│   │   ├── routers/             # API routes — ingest, chat, docs, diagrams, tests
│   │   └── services/            # LLM clients, parsing, orchestrator, indexing
│   ├── db/postgres/schema.sql   # Postgres + pgvector DDL
│   ├── scripts/                 # DB setup, migration, verification
│   ├── data/                    # SQLite (flux.db) + backups
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── src/                     # React + TypeScript source
│   ├── package.json
│   └── vite.config.js           # Vite build (mermaid IIFE fix, chunk strategy)
├── fluxchat/                    # Secure AI Hub — LibreChat-derived submodule
│   └── client/                  # FluxChat React frontend
├── docs/
│   ├── images/                  # Icons and graphics used in README
│   ├── architecture/            # Platform + data architecture docs
│   ├── FLUXCHAT.md              # Secure AI Hub architecture
│   ├── FLUXCHAT_MODE_A.md       # Mode A pilot guide
│   ├── FLUXCHAT_HARDENING.md    # Security hardening phases
│   ├── FLUX_EDGE_SECURITY.md    # nginx rate limits, audit, edge security
│   └── POSTGRES_SETUP.md        # DATABASE_URL, schema, migration
├── docker-compose.yml           # Web + API; profile deps: Postgres + Ollama; profile fluxchat
├── .devcontainer/               # VS Code / Cursor dev container
├── start.sh                     # Dev: backend + frontend + optional Docker services
├── stop.sh                      # Stop all processes + optional Docker services
└── deploy.sh                    # Production Docker stack

Docker Volume Layout

Container path Host mount Purpose
/app/backend/data ./backend/data SQLite, backups, uploads
/app/backend/projects ./backend/projects Indexed codebases, generations
/var/lib/postgresql/data flux_pgdata (named) Postgres data
/root/.ollama ollama_data (named) Ollama models

The API image runs as non-root (uid 1000). If bind-mounted directories are unwritable: sudo chown -R 1000:1000 backend/data backend/projects


Configuration

LLM Provider

Edit backend/.env. See backend/.env.example for all options and comments.

# Pick one (or more — Flux supports runtime switching)
LLM_PROVIDER=anthropic       # or openai / google / azure / ollama
ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AI...

Timezone

# IANA timezone name — default is NZ
APP_TIMEZONE=Pacific/Auckland    # NZST/NZDT (default)
APP_TIMEZONE=Australia/Sydney    # AEST/AEDT
APP_TIMEZONE=UTC

Override without restart via Mission Control → Settings. All storage uses UTC internally.

Azure OpenAI

AZURE_OPENAI_REGION=australiaeast
Region GPT-4o per 1M tokens (in/out) Notes
australiaeast $2.75 / $11.00 ~10% premium over US
eastus $2.50 / $10.00 Baseline
westeurope $2.625 / $10.50 ~5% premium

View live pricing: GET /api/admin/pricing


Roadmap

Roadmap

M0 ──────────── M3 ──────────── M9 ──────────── M14 ────────── M18+
│                │               │                │              │
◉ Start         ◉ OSS Release   ◉ SaaS Beta     ◉ SaaS GA     ◉ Investor Ready
│                │               │                │
│  Phase 1       │  Phase 2      │  Phase 3       │  Future
│  Foundation    │  SaaS Build   │  Enterprise    │  Platform
│                │               │                │
│ • Codebase     │ • Full feat.  │ • SAML/LDAP    │ • Agent marketplace
│   cleanup      │   set + SSO   │   SSO          │ • AIOps integrations
│ • CI/CD        │ • Stripe      │ • SOC 2 cert.  │ • Reseller programme
│   hardening    │   billing     │ • GPU Ollama   │ • Series A readiness
│ • OSS licence  │ • ITSM conn.  │   hosting      │ • 1,000+ users
│ • Community    │ • Admin dash  │ • White-label  │ • APAC + US expansion
│   docs         │ • 250 users   │   option       │
│ • FluxChat     │               │ • 3 enterprise │
│   standalone   │               │   contracts    │
Phase Timeline Target
Phase 1 — Foundation Months 1–3 OSS release, Community + Developer launch
Phase 2 — SaaS Build Months 4–8 250 paying users, Professional tier
Phase 3 — Enterprise Month 9–14 First 3 enterprise contracts, SOC 2
Future — Platform Month 18+ 1,000 users, agent marketplace, Series A

Security & Compliance


Full Audit Trail

Data Residency

Access Control

Compliance
Every prompt, response, and agent action logged with user identity + timestamp Cloud APIs or local Ollama/vLLM — data never leaves your perimeter unless you choose SAML / LDAP / OIDC SSO · Role-based model access · Org usage dashboards SOC 2 Type II · ISO 27001 · APRA CPS 234

Intelligence Credit (IC) System — every AI action has a defined credit cost. Org admins set budgets, monitor consumption in real time, and hard-cap expensive model usage. No surprise bills — AI spend works like SaaS licensing.


API Endpoints

Method Endpoint Description
POST /api/ingest/git Clone & index a git repo
POST /api/ingest/zip Upload & index a ZIP file
GET /api/projects/ List all projects
POST /api/chat/ Stream a chat response
POST /api/docs/generate Generate documentation
POST /api/diagram/generate Generate Mermaid diagram
POST /api/tests/generate Generate unit tests for a file
GET /api/health/postgres Postgres connection health
GET /api/admin/pricing Current LLM pricing by region
GET /api/ui/timezone Current timezone setting

Full interactive docs: http://localhost:8000/docs when the backend is running.


Contributing

Flux is MIT-licensed and open source. Contributions are welcome.

  1. Fork the repo and create a feature branch
  2. Make your changes — include tests where applicable
  3. Open a pull request describing what you changed and why

Licence

MIT — see LICENSE.


Built together

Flux — Engineering Intelligence · Production-proven · Architecturally sound · Built for the engineers who keep everything running.

Overview · Problem · Solution · Features · Get Started · Architecture · Roadmap

About

Flux: Engineering Intelligence. An open-source layer that bridges the gap between messy docs and complex code. Use the Unified Context Engine to map application logic instantly, solve incidents faster, and keep sensitive AU/NZ client data secure and on-shore using local LLMs. It’s your agentic "senior engineer in a box".

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors