InduFlux

InduFlux is a lightweight private IIoT process data ingestion and visualization platform for offline factory LAN deployments.

It is designed for workshops that need to collect high-frequency production records from PLCs, inspection stations, MES adapters, or barcode workflows while keeping data inside a local network. The backend validates dynamic JSON payloads, stores append-only records in PostgreSQL, supports workspace membership and table ownership, and prepares data for queries and dashboards.

Chinese documentation: README.zh-CN.md

What Is Included

• Python 3.12 backend built with FastAPI, PostgreSQL-oriented domain logic, and uv workflows.
• Vue 3 frontend built with Element Plus, ECharts-ready dashboard surfaces, zh-CN / en-US UI catalogs, and Playwright e2e tests.
• Dynamic table metadata for IIoT fields such as barcode, choice, decimal, datetime, and JSON object payloads.
• API Key ingestion flow for device writes, including validation and localized error messages.
• Query, analytics, table moves, and workspace member management.
• Docker Compose and Nuitka deployment assets for single-machine factory servers.

Repository Layout

src/induflux/        Backend application, domain logic, persistence, workers
frontend/           Vue 3 frontend, Vite build, Playwright e2e tests
tests/              Python unit/integration/static contract tests
docs/               English usage and design documentation
docs/zh-CN/         Chinese usage documentation
deploy/             Docker and Nuitka deployment assets

Requirements

• Python 3.12
• uv
• Node.js and npm
• PostgreSQL for real deployment or database integration work
• Docker Compose if using the containerized deployment path

Install Python dependencies:

uv sync

Install frontend dependencies:

cd frontend && npm ci

Quick Start

Run backend tests:

uv run pytest

Run the frontend in development mode:

cd frontend && npm run dev

Build the production frontend:

cd frontend && npm run build

Run real browser e2e tests:

cd frontend && npm run test:e2e

The Playwright suite starts an isolated Vite server and drives Chromium through login, locale switching, table fields, workspace members, API Key management, ingestion debug, query filters, table moves, and chart creation.

Frontend Tutorial

1. Start the dev server with cd frontend && npm run dev.
2. Open the printed Vite URL in a browser.
3. Register the first administrator or sign in with an existing account.
4. Select a workspace, add a dynamic table field, and confirm it appears in the field table.
5. Create a workspace API Key and store the one-time plaintext securely.
6. Paste an operator-created device key into the ingestion debugger and send a real payload using one of the generated language examples.
7. Run structured record queries and trend, bar, or pie analytics.
8. Invite workspace members, choose editor or viewer access, and move tables between workspaces you own when needed.

Every business workflow uses the versioned /api/v1 backend API.

Operational Tutorial

On normal deployment startup, InduFlux initializes the database automatically:

• applies the idempotent baseline schema;
• creates rolling daily production_records partitions;
• uses INDUFLUX_AUTO_PARTITION_DAYS to decide how many future partitions to create.

The first registered user becomes the protected system_admin account. It cannot be demoted, disabled, or deleted. System administrators use the account management page to register users, disable or enable users, change passwords, and toggle free registration. There is no separate code or CLI path for bootstrapping the first administrator.

Every registered or administrator-created user receives a personal workspace. This pre-release schema targets a new database; no migration history is needed before the first deployment.

The induflux-ops init-db and create-partitions commands remain available only for inspecting SQL or emergency offline maintenance.

Deployment

Docker Compose deployment:

docker compose up --build --force-recreate --wait
curl http://localhost:8000/health

The Compose setup runs PostgreSQL and a single backend service. The backend image builds the frontend during docker compose build, then serves both API routes and frontend/dist on port 8000 with Gunicorn's native asgi worker.

One-click startup (recommended):

./scripts/start.sh

This script loads defaults from .env, builds the frontend, initializes the database, and starts one Uvicorn listener on 0.0.0.0:8000. Explicit INDUFLUX_* process variables take precedence over .env. Open http://<server-lan-ip>:8000; the SPA and /api/v1 use the same port.

Nuitka binary deployment:

./scripts/build.sh

The build script runs tests, installs and builds the frontend, runs Playwright, and compiles the Nuitka binary. Use the templates in deploy/nuitka/ for Linux systemd startup. This path expects a local PostgreSQL installation.

Documentation

• Device ingestion API
• Data model
• Frontend scaffold and tests
• User guide
• Operational commands
• Performance notes
• Backend i18n
• Docker Compose deployment
• Nuitka deployment
• Implementation plan

Chinese versions are available under docs/zh-CN.

Verification Checklist

Run the complete release gate before handing off changes:

./scripts/verify.sh

It enforces backend/frontend coverage, type checking, unit tests, a production build, single-port startup, and production Playwright workflows.