smallfactory
# smallFactory [](https://github.com/yusufm/smallfactory/stargazers) [](https://github.com/yusufm/smallfactory/blob/main/LICENSE) [](https://github.com/yusufm/smallfactory/commits/main) [](https://discord.gg/g3QSuVmvBt) [](https://ko-fi.com/T6T21UH4X8) **For solo founders and tiny hardware teams who are tired of spreadsheet chaos but don't need enterprise PLM.**  ## What is smallFactory A Git-native toolset for small teams to manage the things they make. - Design - Manage part/assembly metadata, drawings/CAD/notes files, BOMs, etc. - Snapshot - 1-click revision control of parts. - Build - Track built parts, serial numbers, test results, photos, etc. - Manage inventory. ## Why smallFactory Read the [smallFactory Story](docs/meta/the-smallfactory-story.md) - Built for small teams: minimal setup, low overhead, fast workflows. - Git-native and portable: plain files under Git; diffs, reviews, history. No database, no lock‑in. - Opinionated, simple standard: Entities, BOMs, Revisions, Inventory, Files in a consistent layout. - Tools that fit your flow: CLI and lightweight web UI; human/JSON/YAML output; commits locally, pushes if origin exists. - Extensible by design: readable YAML/JSON so you can script, automate, and integrate. ## Prefer turnkey? smallFactory Cloud (Fully Managed) Want everything smallFactory offers without running servers? smallFactory Cloud is our fully managed, multi-tenant hosting—so you can focus on building, not babysitting infrastructure. Get started: https://www.exploresf.com ## Quickstart Get up and running with smallFactory inventory management in a few simple steps: ```sh # Setup (once) # Prereqs: Python 3 and Git installed # Clone the smallFactory core repo $ git clone https://github.com/yusufm/smallfactory.git smallfactory $ cd smallfactory # Optional: create and activate a virtual environment $ python3 -m venv .venv && source .venv/bin/activate # Install CLI dependencies $ python3 -m pip install -r requirements.txt # Optional: Web UI + MCP dependencies (if you plan to run the web app / MCP endpoint) $ python3 -m pip install -r web/requirements.txt # Initialize by cloning the example datarepo # 1. Fork the sample data repository on GitHub by going to this URL (or through the fork button on the sample repo): https://github.com/yusufm/smallfactory_test_datarepo/fork # 2. Clone using YOUR fork of the sample data repo $ python3 sf.py init --github-url [email protected]:<YOUR-USERNAME-HERE>/smallfactory_test_datarepo.git # Start the web server $ python3 sf.py web # Access the web UI http://127.0.0.1:8080 # Note: All mutating CLI operations automatically create a Git commit (and push if an origin exists). # Commit messages include machine-readable tokens like ::sfid::<SFID>. ``` ## Docker smallFactory now supports a single-image Docker workflow for both the web app and ad hoc CLI usage against the same persisted data repo. Quick start with the official image: ```sh docker pull ghcr.io/yusufm/smallfactory:latest docker run --rm -it -p 8080:8080 -v smallfactory-data:/data ghcr.io/yusufm/smallfactory:latest # Web UI: http://127.0.0.1:8080 # MCP: http://127.0.0.1:8080/mcp ``` Run CLI commands without attaching to the running container: ```sh docker run --rm -it -v smallfactory-data:/data ghcr.io/yusufm/smallfactory:latest inventory onhand --readonly docker run --rm -it -v smallfactory-data:/data ghcr.io/yusufm/smallfactory:latest entities ls ``` For reproducible deployments, prefer an explicit release tag instead of `latest`. If you are working from a local checkout and want to build from source instead: ```sh docker compose up --build docker compose run --rm smallfactory inventory onhand --readonly ./scripts/sf-docker.sh inventory onhand --readonly ``` Container defaults: - Data root: `/data` - Data repo: `/data/datarepo` - Config: `/data/.smallfactory.yml` If `/data/datarepo` is empty, the container will clone `SF_REPO_GIT_URL` on first start, or initialize a fresh smallFactory repo if no Git URL is provided. See the full guide: [Docker guide](docs/users/docker.md) ## Community Join the smallFactory Discord: https://discord.gg/g3QSuVmvBt ## Features at a glance ### Design - **Entities** — Organize parts, assemblies, and locations with names, tags, and metadata. - **Files workspace** — Upload, organize, and download design files and documents; snapshots captured in revisions. - **BOM** — Manage bills of materials with alternates; edit in the app; see structure at a glance.   ### Build & release - **Revisions** — One‑click, numbered revisions with clear release tracking. - **Build events** — Capture timeline events on builds (`b_*`) with notes, tags, and attachments. - **Stickers** — Generate QR stickers for parts and locations; print in batches with chosen fields. - **Camera capture** — Snap a photo of an invoice or label to auto‑extract parts data. - **Vision‑assisted intake** — Extract parts from invoices and batch‑create with review.  ### Operate - **Inventory** — Track quantities by location; adjust quickly with mobile QR scanning. - **Mobile access** — Optimized for phones with simple, touch‑first flows. - **Search & dashboard** — Find parts fast and see key stats at a glance. - **QR‑first workflows** — Label, scan, and act quickly on the floor.  <p> <img src="docs/img/screenshots/mobile_adjust_scan_1.jpeg" width="250"> <img src="docs/img/screenshots/mobile_adjust_scan_2.jpeg" width="250"> </p> ### Vision Use a camera or upload to extract parts from invoices and batch-create entities. <p> <img src="docs/img/screenshots/mobile_partscan_1.jpeg" width="250"> <img src="docs/img/screenshots/mobile_partscan_2.jpeg" width="250"> <img src="docs/img/screenshots/mobile_partscan_3.jpeg" width="250"> </p> ### Platform - **Git‑native workflow** — Your product data lives in Git. Simple, transparent, and portable. - **Collaboration & history** — Work as a team with reviewable changes and a full history. - **Local‑first** — Runs on your machine; you control your data and workflow; automatically updates your remote Git repo when configured. - **Web UI** — Fast, clean, responsive interface with search and inline editing. - **CLI** — Powerful command‑line for automation; human‑ or machine‑readable output. - **Validation** — Built‑in checks to catch mistakes early. - **Custom fields & tags** — Capture the details that matter to your business. - **Simple onboarding** — Start in minutes with an example repository. ### AI / MCP - **Integrated MCP endpoint** — Run once with `sf.py web`; MCP is served at `/mcp` on the same port. - **BYO AI client** — Connect Windsurf, Cursor, Claude Desktop, Codex, and other MCP-compatible clients. - **Ask free-form questions** — Ask natural-language questions about your parts, builds, inventory, and repair history. - **Read-only analytics tools** — Query entities, inventory, BOM, build events, and aggregated repair trends. - **Resource compatibility** — Includes MCP resources for clients/modes that prefer resource reads over tool calls. Example prompts: - `Which repairs are most common across all builds for part p_xyz?` - `Create a DigiKey order for low-stock items needed to build 5 units of p_xyz.` Quick start: ```bash python3 -m pip install -r web/requirements.txt python3 sf.py web --port 8080 # MCP endpoint: http://127.0.0.1:8080/mcp ``` See full setup + client configs: [MCP integration guide](docs/users/mcp.md) ## GET endpoints are pure (no side effects) - All HTTP GET routes avoid cache writes and Git mutations. - Inventory reads in the web app use the read‑only helper `inventory_onhand_readonly()`. - CLI parity: use `sf inventory onhand --readonly` to compute on‑hand without writing caches. --- ## What to read next - [The smallFactory Story](docs/meta/the-smallfactory-story.md) - [Start Here](docs/START_HERE.md) - [Users docs](docs/users/README.md) - [MCP integration guide](docs/users/mcp.md) - [Build events guide](docs/users/events.md) - [Developers docs](docs/developers/README.md) - [Web UI docs](web/README.md) - [CLI docs](docs/cli/README.md) - [Core spec](smallfactory/core/v1/SPECIFICATION.md)