ManuFlow ERP

ManuFlow is a localhost manufacturing and warehouse ERP built with FastAPI, SQLAlchemy 2, PostgreSQL 16, React, TypeScript, and Vite. It has no login, user-profile, or AI features. It uses original ERP workflows and code.

Requirements

• Docker Desktop with Docker Compose v2
• Python 3.11 or newer
• Node.js 18 or newer and npm

First run

1. Copy the repository-root .env.example to .env. The example credentials are for local development only.

2. Install backend dependencies:

   cd backend
   python -m venv venv
   .\venv\Scripts\Activate.ps1
   pip install -r requirements.txt
   cd ..

   On macOS/Linux, activate with source backend/venv/bin/activate.

3. Run npm install in frontend.

4. From the repository root, run make dev or npm run dev.

The launcher checks Docker ownership and configured ports, starts PostgreSQL, applies Alembic migrations, verifies database identity, and configures the read-only reporting role. If the database has no items, it asks before loading standard master demo data.

Configuration

The repository-root .env is the only settings file. Copy .env.example once, then configure COMPOSE_PROJECT_NAME, API_HOST, API_PORT, WEB_PORT, DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, TEST_DB_NAME, READONLY_DB_USER, and READONLY_DB_PASSWORD there. DB_VOLUME_NAME identifies the isolated Docker data volume and normally remains manuflow_pgdata. Backend URLs are built from these values. Vite, Uvicorn, Docker Compose, Alembic, pytest, and database scripts read the same file. PostgreSQL stays on its standard container port; its host port binds only to loopback.

Run make ports to see each configured port and its current listener. make dev checks for clashes. If a port is busy, it identifies the process/container and asks before saving the next free port to .env. Declining leaves the configuration unchanged. Compose assigns the database container a project-specific name, so separate checkouts can run side by side when their host ports differ. If a legacy fixed-name database container from this same checkout is detected, startup asks before recreating only that container; it preserves and reattaches its data volume. A container owned by another project is left alone. Exported shell variables that differ from .env produce a warning and override it for that process.

Database commands

Root npm scripts wrap scripts/db.py:

Command	Effect
npm run db:up	Start PostgreSQL in the background.
npm run db:down	Stop/remove the Compose container; keep the data volume.
npm run db:reset	Require typing RESET MANUFLOW DATABASE, then remove only the manuflow_pgdata volume. This permanently deletes local DB data.
npm run db:backup	Write a timestamped custom-format dump under backups/.
npm run db:restore -- backups/manuflow-YYYYMMDD-HHMMSS.dump	Replace the timestamp with a filename; the command asks before replacing DB contents.
npm run db:psql	Open psql in the running container.

Backups are ignored by Git. Keep copies outside the checkout if you need independent retention. To connect with a GUI, use DB_HOST, DB_PORT, DB_NAME, DB_USER, and DB_PASSWORD from .env. The reporting account uses READONLY_DB_USER and READONLY_DB_PASSWORD and can select only from the analytics views.

Schema, seeds, and legacy import

Alembic migrations are the schema source of truth. Startup does not call create_all. To migrate explicitly:

cd backend
.\venv\Scripts\python.exe -m app.db_init

Run python -m app.seed for master demo data, python -m app.seed --sample-flow for standard sample transactions, or python -m app.seed --rich (or npm run db:seed:rich) for a comprehensive, multi-month operational dataset (50+ orders, production runs, invoices, shipments, downtime logs, and financial records). None of the seeds run automatically.

PostgreSQL is the only runtime/test database. The optional one-time importer reads a legacy SQLite file:

cd backend
.\venv\Scripts\python.exe -m app.tools.sqlite_to_postgres --sqlite path\to\legacy.db

The importer verifies row counts, stock balances, and GL balances. It refuses to replace populated target data unless --force is passed; back up and check DB_NAME before using that option.

Tests

Tests use TEST_DB_NAME. Pytest aborts unless the database name ends in _test, the DB host is loopback, and its port equals DB_PORT. The fixture migrates the test database and truncates its tables at session start. Never point it at data you need.

cd backend
.\venv\Scripts\python.exe -m pytest -q

The suite covers business rules, migrations, role grants, the legacy importer, test database safety, and concurrent stock/document numbering.

Troubleshooting

• Port in use: run make ports. make dev identifies the owner and offers to select and save the next free port; it never stops another process. You can also edit that port in .env.
• Authentication failed: check DB_USER, DB_PASSWORD, and DB_NAME against the initialized database. Changing Compose credentials does not rotate an existing PostgreSQL role password.
• Stale environment variable warning: unset the named exported variable or update .env to the intended value, then start a fresh shell.
• Frontend loads but API fails: check API_HOST and API_PORT, inspect make ports, and verify the backend passed database identity and marker checks.
• Docker unavailable: start Docker Desktop and retry make dev.
• Windows init-script line endings: check docker compose logs db and save files under docker/initdb with LF line endings.
• Schema behind: run python -m app.db_init from backend and review the Alembic error.
• Tests cannot connect: start Docker and verify TEST_DB_NAME, DB_HOST, and DB_PORT satisfy the pytest safety rules.

Assumptions and limits

• PostgreSQL 16 is the supported database. SQLite is used only by the opt-in importer and its temporary-file test.
• The .env.example credentials are development-only. Keep .env ignored and change credentials for shared deployments.
• Container shutdown preserves the named volume. Reset requires typed confirmation.
• Demo transactions are synthetic, currency is INR, and stock valuation uses moving weighted average; FIFO and amendment/versioning are not implemented.
• Timestamps are UTC and monetary/quantity values use decimal arithmetic.
• Proof-of-delivery files live locally under backend/data/pod and are not included in database dumps.
• Workstation utilization assumes eight hours per day per unit; OTIF compares delivery with the Sales Order delivery date.
• Landed Cost records workflow and charges; allocation into inventory valuation is not implemented.

License

Original project code. Not derived from ERPNext or GPL-licensed code.