Batchivo

Self-hosted 3D printing business management platform

---

What Is Batchivo?

Batchivo is a self-hosted SaaS platform for running a small 3D printing business: filament inventory, products and BOMs, production runs, orders, pricing, shipping, analytics, and marketplace/shop workflows.

It started as a spreadsheet for tracking real 3D printing work and has grown into a multi-tenant FastAPI/React application intended for private use first, then a public open-source MVP.

---

Current Status

Version: 0.2.0-alpha Stage: Pre-MVP hardening Issue tracker: Beads (bd) Last status refresh: 2026-05-01

The project is close to a usable MVP for the core 3D printing workflow. The main product surfaces are implemented, but the backlog still needs E2E coverage, production deployment validation, issue triage after the Task Master migration, and several expansion features.

Implemented Core

• Multi-tenant authentication, onboarding, tenant membership, settings, modules, and audit surfaces
• Spool, consumable, material, QR/label, scan, and inventory transaction workflows
• Product catalog with BOMs, costing, images, categories, variants, designers, SKU and export support
• Production run API and UI, including plates, completion, variance analysis, reprints, and inventory adjustments
• Orders, customers, sales channels, discounts, returns, shipping rates, newsletter, public shop, and customer account surfaces
• Dashboard, analytics, forecasting, reporting/export, and admin configuration APIs
• Printer fleet foundations: printers, Bambu integration surface, print queue, WebSocket status, and generic webhooks
• Shopify sync/webhook groundwork and Square/payment settings surfaces
• Local Docker Compose, k3s/Cloudflare self-hosting assets, observability configuration, and CI

MVP Gaps

• E2E coverage for full order/payment/fulfillment workflows is still open in Beads.
• Production deployment needs a fresh end-to-end validation, including wildcard DNS/domain configuration.
• Beads contains imported Task Master issues that need triage because some imported descriptions are stale relative to the code.
• Knitting/multi-craft modules are not MVP-ready: module definitions exist, but yarn/needle routers are placeholders and pattern/project API routers are not implemented.
• Structured production logging, alert rules, complete COGS, marketplace OAuth integrations, and advanced printer automation remain post-MVP or hardening work.

Use docs/PROJECT-STATUS.md for the current status snapshot and ROADMAP.md for phase-level priorities.

---

Tech Stack

Backend

• Python 3.12+ with FastAPI
• PostgreSQL with multi-tenant isolation and SQLAlchemy 2.0
• Alembic migrations
• Redis and Celery-ready background job infrastructure
• OpenTelemetry, Prometheus, Grafana, Tempo, and Loki configuration

Frontend

• React 19, TypeScript 5.9, Vite 7
• TanStack Query
• Tailwind CSS and local component primitives
• PWA support and responsive admin workflows

Infrastructure

• Docker Compose for local development
• k3s/Kubernetes manifests
• Cloudflare Tunnel ingress
• Self-hosting documentation and observability assets

---

Quick Start

Prerequisites

• Docker and Docker Compose
• Python 3.12+
• Node.js 20+
• Poetry
• pnpm or npm

Local Development

git clone https://github.com/techize/batchivo.git
cd batchivo

docker-compose up -d

cd backend
poetry install
poetry run alembic upgrade head
poetry run uvicorn app.main:app --reload --port 8000

cd ../frontend
pnpm install
pnpm run dev

Access

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API docs: http://localhost:8000/docs
• Grafana: http://localhost:3000

---

Issue Tracking

This repository uses Beads.

bd ready
bd show <id>
bd update <id> --status in_progress
bd close <id> --reason "Completed"
bd export --output .beads/issues.jsonl

The old Task Master backlog was migrated into Beads on 2026-05-01. Beads is now the source of truth.

---

Documentation

• Project Status
• Roadmap
• Development Guide
• Testing Guide
• Self-Hosting Guide
• Database Schema
• Production Runs
• API Reference
• User Guide
• Implementation Phases

---

Testing

make test

cd backend && poetry run pytest
cd frontend && pnpm test

Last verified snapshot from the Beads repair session on 2026-05-01:

• Backend: 3634 passed, 19 skipped
• Frontend unit tests: 334 passed
• Frontend production audit: 0 vulnerabilities
• Landing build: passed

---

Development Commands

make dev          # Start full local development stack
make test         # Run tests
make lint         # Run linters
make format       # Format code
make migrate      # Run database migrations
make build        # Build Docker images
make deploy-dev   # Deploy to k3s dev environment

See Makefile for all available commands.

---

Deployment

Batchivo is designed for self-hosting on:

• k3s or another lightweight Kubernetes environment
• PostgreSQL
• Redis
• Cloudflare Tunnel
• Prometheus, Grafana, Tempo, and Loki

See docs/SELF-HOSTING.md for the current deployment guide.

---

Security

• Custom JWT authentication with secure refresh tokens
• Multi-tenant data isolation
• Pydantic request validation
• SQLAlchemy ORM query construction
• Environment-based secrets
• TLS via Cloudflare in the intended deployment

Report vulnerabilities privately to the repository owner.

---

License

This project is expected to be released under MIT or Apache 2.0 once the MVP is stable.

Current status: private repository during initial MVP development.

---

Vision

Short term: robust personal 3D printing business management Medium term: public open-source MVP and community feedback Long term: practical operations platform for small 3D printing businesses

Last updated: 2026-05-01