# ElectroGen AI — Full Documentation for AI Assistants

> ElectroGen AI (https://electrogen.org) is an AI-powered electronics project generator, planner, and simulator. A user describes a project idea in plain language ("a plant monitor that texts me when the soil is dry") and ElectroGen produces a complete, buildable engineering blueprint — parts list, wiring, firmware, CAD, cost estimate, and preview renders.

Canonical machine-readable entry points:

- LLM index: https://electrogen.org/llms.txt (this file is the extended version)
- OpenAPI spec: https://electrogen.org/openapi.yaml
- Plugin manifest: https://electrogen.org/.well-known/ai-plugin.json
- MCP endpoint (JSON-RPC 2.0): https://electrogen.org/api/mcp
- Sitemap: https://electrogen.org/sitemap.xml

## What the product does

ElectroGen turns a natural-language brief into a complete electronics project blueprint. Given a prompt, it:

1. Chooses a platform (Arduino, ESP32, Raspberry Pi, or generic/custom MCU) and optionally a specific board variant.
2. Generates a structured blueprint: title, description, difficulty, estimated time, total cost.
3. Produces a BOM of hardware items (sensors, MCUs, actuators, power, passives) with component types, recommended vendors, and real purchasable links (Amazon, Adafruit, AliExpress, etc.).
4. Generates the wiring/connection map (pin-to-pin) and an interactive schematic visualization with smart pin routing.
5. Writes complete, commented firmware (C++ for Arduino/ESP32, Python for Raspberry Pi) plus pinout headers for Arduino / ESP-IDF / Python generated from the IO map.
6. Runs engineering validation: mixed-voltage and logic-level checks, pin-mux conflicts (including ESP32 strap/flash pins and STM32 family catalogs), I2C/SPI fan-out limits, power-budget and pneumatic/hydraulic consistency warnings.
7. Optionally generates CAD: OpenSCAD source for enclosures/mounts and headless FreeCAD/Blender exports (STEP, STL, OBJ, GLTF) with print settings (material, infill).
8. Renders photorealistic preview images of the finished prototype (hero/top/side/cutaway views).
9. Produces supporting engineering docs: test plan, calibration guide, failure analysis, substitution guide, maintenance guide, safety checklist, regulatory hints, UX guide, supply-chain guide, fabrication guide.

The user can then iterate conversationally ("switch to solar power", "move the sensor to the back") via the Improve flow, which produces a new version of the blueprint. Projects support families/versions (v0.01, v0.02, ...), archiving, JSON import/export, browser-local persistence (IndexedDB, works without an account), and optional cloud sync when signed in.

## Who it is for

- Hobbyists and makers who want a working parts list, wiring diagram, and firmware without spec-sheet archaeology.
- Students and educators learning electronics with guided, safety-checked designs.
- Engineers and prototypers who want a fast first draft (BOM + firmware + CAD) to iterate on.
- Product designers who want a rendered preview and printable enclosure of a concept.

## How it works end-to-end

Prompt -> Blueprint -> BOM -> Wiring -> Firmware -> Engineering checks -> CAD -> Preview render:

1. The user types a brief on /create (optionally choosing a platform and "electromechanical" vs "mechanical-only" mode).
2. The backend (Express, Node.js) calls AI providers — Google Gemini primary, with optional OpenAI / xAI / OpenRouter fallbacks — to generate a structured JSON blueprint.
3. The blueprint is enriched server-side: pin auto-assign (/api/pinmux/auto-assign), engineering warnings, vendor links, cost rollups.
4. The SPA renders it: dashboard cards, interactive schematic graph, code editor, engineering warnings tab, fabrication tab.
5. Preview renders are generated on demand (Gemini image models with OpenAI/xAI fallbacks), and CAD binaries via headless FreeCAD/Blender runners (sandboxed: no network, memory/CPU caps).
6. Projects save locally in IndexedDB by default; signed-in users can sync to Postgres, share to the community, and get public permalinks at /{handle}/{slug}.

## Plan tiers

Usage is metered by action type. Actions: `blueprint` (generate a new project blueprint), `improve` (iterative refinement of an existing blueprint), `image` (AI preview render). Quotas per tier:

| Tier | Window | Blueprints | Improvements | Preview images |
|------|--------|-----------:|-------------:|---------------:|
| Free | daily | 2 / day | 1 / day | 1 / day |
| Starter | monthly | 20 / month | 40 / month | 20 / month |
| Pro | monthly | 80 / month | 160 / month | 80 / month |

Free resets daily; Starter and Pro reset monthly. Paid tiers are billed via Stripe (checkout + customer portal endpoints exist; they are not part of the public read API). Generating blueprints/previews requires a free Google sign-in; browsing community projects, the marketplace, news, and all public GET endpoints requires no account.

## Public API surface (read-only, no auth)

Base URL: https://electrogen.org — most endpoints also mirror under the bare host (routers are mounted at both / and /api, but the /api-prefixed paths are canonical). Exception: /api/news* is mounted under /api only — a bare /news mount would shadow the /news article pages.

- GET /api/health — `{ "status": "ok" }` liveness.
- GET /api/capabilities — runtime capabilities: `db.enabled`, `auth.provider` / `auth.serverAuthEnabled`, `ai.providers` / `ai.anyEnabled` / `ai.providerHealth` (sanitized), `planQuota` (per-user; null when anonymous), `planCatalog` (tier table above).
- GET /api/site-config — public site SEO/analytics configuration.
- GET /api/community-projects — `{ projects, groups }`; card-shaped public projects with owner identifiers stripped; capped server-side (max 200).
- GET /api/community-projects/{id} — `{ project }`; full public blueprint for a community-shared, non-archived project. Owner fields are never returned.
- GET /api/community-projects/{id}/preview — prototype preview image (302 redirect or image bytes).
- GET /api/component-products — `{ items, generatedAt, cacheTtlSeconds }`; component marketplace catalog (name, brand, category, tags, price range, availability, rating, affiliate/vendor links).
- GET /api/component-news — `{ items, generatedAt }`; aggregated electronics/component news items.
- GET /api/news — `{ items, generatedAt, cacheTtlSeconds }`; published ElectroGen news/blog posts (list view omits bodies; `limit`/`offset` paginate).
- GET /api/news/{slug} — `{ post }`; full article including the markdown body. /api-only mount.
- GET /api/public/{handle}/{slug} — `{ project, versions, owner: { handle }, canonical }`; read-only shared-project permalink data.
- POST /api/mcp — Model Context Protocol endpoint (JSON-RPC 2.0 over HTTP). Methods: initialize, ping, tools/list, tools/call. Tools: `list_public_projects`, `get_component_products`, `list_news_posts`, `get_capabilities`, `describe_platform`. Rate-limited per IP; GET returns 405 (no SSE stream).

Everything else under /api (project sync, AI generation endpoints, billing, admin, telemetry, feedback) requires authentication or admin keys and is intentionally not part of the public read surface.

## Authentication model (for context)

Google Identity Services on the client -> POST /api/auth/google verifies the Google ID token -> server issues an HMAC session token sent as a Bearer token. Anonymous visitors can browse everything and try the planner UI, but AI generation endpoints enforce plan quotas keyed by a signed-in user. Signed-in users get synced projects, plan quotas, and community sharing. Admin routes are gated by an ADMIN_EMAILS allowlist.

## Links

- App: https://electrogen.org/
- Create a project: https://electrogen.org/create
- Community projects: https://electrogen.org/community
- Component marketplace: https://electrogen.org/marketplace
- News: https://electrogen.org/news
- Source-quality info for crawlers: https://electrogen.org/robots.txt