StepMaker

Link to the presentation

Generate consistent, multilingual work instructions automatically from CAD assemblies. Runs completely offline — your data never leaves your premises.

What is StepMaker?

StepMaker is an offline-first platform that transforms CAD assemblies into clear, step-by-step work instructions and assembly handbooks. It combines an interactive 3D viewer with a FastAPI backend capable of analyzing STEP files, deriving assembly sequences, and generating professional HTML/PDF handbooks. The system is designed for privacy-first, air‑gapped environments with zero cloud dependencies.

Highlights from the landing page:

• Interactive 3D Viewer: Visualize and inspect assemblies, select components, and understand structure.
• Offline Architecture: Designed to run entirely on local infrastructure (air‑gapped ready).
• Privacy & Security: No telemetry, no data leaves your network.
• Highly Efficient: Local processing for fast CAD parsing and instant generation.

Architecture at a glance

This repo ships with a Docker Compose stack:

• frontend (Next.js) — http://localhost:3000
• backend (FastAPI) — http://localhost:8000 (Swagger docs at /docs in non‑prod)
• ollama (optional, local LLM server) — http://localhost:11434
• redis (utility service)

Key backend capabilities:

• STEP/STP processing and graph derivation for assembly relationships
• Assembly handbook generation with multi‑view images and AI‑assisted step text
• HTML/PDF rendering pipeline

Quickstart (Docker Compose)

Prerequisites:

• Docker
• Docker Compose

Basic run:

# From the repository root
docker compose build
docker compose up -d

Then open:

• Frontend UI: http://localhost:3000
• API docs: http://localhost:8000/docs

Notes:

• The backend is preconfigured to talk to the Ollama service at http://ollama:11434/api/chat.
• To have the Ollama container auto‑pull a model on start, set an environment variable before running compose (for example in a .env file in the repo root):

# .env
OLLAMA_MODEL_NAME=qwen2.5vl:3b

The backend defaults to model name qwen2.5vl:3b. If you prefer online generation with Google Gemini, provide GEMINI_API_KEY and set USE_ONLINE_LLM=true in the backend environment; otherwise the system will operate fully offline using Ollama or fall back to safe defaults for instruction text.

Core features

• 3D assembly exploration (browser)
• STEP file analysis and connection graph derivation
• Assembly sequence validation helpers
• Assembly handbook generator
  • Progressive images per step (cumulative + individual component views)
  • Consistent color assignment per component and progressive opacity
  • Optional final assembly 4‑view grid
  • AI‑assisted step text (local Ollama vision/chat or online Gemini)
  • HTML and PDF outputs

API overview (selected)

• Health: GET /health — service status
• Chat/Completion: GET /api/v1/chat/completion?prompt=...
• PDF/Handbook: POST /api/v1/utils/generate-pdf
  • generation_type: "assembly_handbook" or simple text
  • component_list: ordered list of components for assembly
  • step_file_path: path to a STEP file (inside container or mounted /app/data)
• STP Graph:
  • POST /api/v1/graph/upload-stp — upload a STEP/STL file, creates a UUID session
  • POST /api/v1/graph/analyze-stp — derive component graph for a session
  • POST /api/v1/graph/verify-connection — verify connection sequence
  • GET /api/v1/graph/session/{session_id} — view session files and cache

Swagger UI is available at http://localhost:8000/docs in non‑production.

Configuration tips

• Ollama model selection (optional, for auto‑pull in the ollama container):
  • Set OLLAMA_MODEL_NAME in your environment or .env (e.g., qwen2.5vl:3b)
• Backend LLM routing:
  • USE_ONLINE_LLM=true with GEMINI_API_KEY for online Gemini vision
  • Otherwise, the backend uses local Ollama or safe text fallbacks
• Volumes:
  • backend mounts ./backend/src to /app/src and ./backend/data to /app/data
  • frontend mounts ./frontend/src to /app/src

Tech Stack

Frontend:

• Next.js 15, React 19, TypeScript
• Tailwind CSS 4, Radix UI, Framer Motion
• Three.js with React Three Fiber and Drei
• occt-import-js (WebAssembly OpenCascade bindings) for CAD in the browser
• TanStack Query, Axios

Backend:

• FastAPI (+ Uvicorn/Gunicorn)
• Pydantic v2, SlowAPI (rate limiting), httpx
• PythonOCC (OpenCascade), trimesh, numpy, scipy for geometry
• Playwright-based HTML/PDF rendering pipeline

Infra:

• Docker Compose: frontend, backend, ollama, redis
• Ollama for local LLMs (vision/chat)

License (AGPL-3.0-only)

Copyright (c) 2025 StepMaker contributors

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

You may copy, distribute, and modify it under the terms of the AGPL-3.0. If you run a modified version of this program on a server and let other users communicate with it there, you must also make the source code available to those users.

SPDX-License-Identifier: AGPL-3.0-only

Full license text: https://www.gnu.org/licenses/agpl-3.0.txt