Design Intelligence Platform

This repo is a local-first MVP for structured early-stage product design work.

It is not a general autonomous design engineer. It is a web app that helps you turn a product description or a manually entered workspace into:

• a function tree
• a simple physical decomposition and DSM
• a morphological chart
• a seeded TRIZ lookup
• a seeded axiomatic design matrix
• a weighted concept ranking
• an audit trail of module runs

What It Actually Is Today

• apps/web: React + Vite dashboard for editing a workspace and viewing module outputs
• apps/api: FastAPI backend with deterministic method engines plus optional Ollama narration/parsing
• apps/api/design_intelligence/data: small local knowledge corpus and a seeded TRIZ matrix
• apps/api/design_intelligence/data/archetypes: canonical product-family and machine-archetype packs used to seed supported intake cases
• docs/mechanical-engineering-knowledge-sources.md: the external mechanical-design sources currently distilled into the local corpus
• apps/api/.local/sessions.json: default local persistence for session history and decision events

The current product is best understood as:

• a structured design-methods sandbox
• a local prototype for inspectable design reasoning
• a seeded concept-generation workflow

It is not yet a production-grade design intelligence system.

What Works

• Description-driven intake orchestration: A free-text product description can be turned into a structured WorkspaceRequest. Supported archetypes now seed different content from explicit pack files instead of sharing one generic machine fallback.
• Inference provenance: The intake response now shows field-by-field source, confidence, and warnings when the inferred structure stays generic.
• Clarification gate: If a prompt is too short or does not match a supported archetype pack strongly enough, the app stops at clarification questions instead of silently accepting weak structure.
• Manual workspace editing: You can directly edit product setup, flows, sub-functions, components, TRIZ inputs, FRs, DPs, matrix values, and weights.
• Functional decomposition: The backend generates a function tree and flow summary, and the seeded content is now more specific for grinder, sorter, drill, conveyor, and similar cases.
• Physical decomposition: The backend generates a simple component tree, interface list, and DSM.
• Morphological chart: Rows are generated from sub-functions. Library suggestions are opt-in. Missing means are shown as explicit GAP states.
• TRIZ: Contradictions are looked up deterministically from the seeded 1-10 matrix.
• Axiomatic design: The app classifies the FR/DP matrix and computes independence and information scores.
• Concept synthesis: Concepts are scored with a weighted matrix. If morphology gaps exist, scoring is blocked instead of faking confidence.
• Audit trail: Every module run is recorded as an immutable decision event inside a session.
• Event diffing: The audit panel can compare two recorded events and show which request or response fields changed.

What The Intake Orchestrator Really Does

POST /api/intake/orchestrate is a seed generator, not a trusted expert decomposition engine.

The current behavior is:

• If Ollama is available: The backend asks the model for JSON containing top-level function, flows, sub-functions, components, a likely TRIZ contradiction, and candidate FRs/DPs.
• If a supported archetype pack matches: The backend seeds the workspace from that pack and treats it as the primary deterministic source for structural fields.
• If Ollama is unavailable or returns unusable output: The backend falls back to deterministic product-family logic, but unsupported structures remain draft-only and are expected to trigger clarification.
• In both cases: The result is normalized into a valid WorkspaceRequest, and only accepted workspaces continue into the normal deterministic modules.

What this means in practice:

• The intake path gives you a plausible starting workspace.
• For supported packs such as mechanical pencils, drills, coffee grinders, conveyors, conveyor sorters, mixers, and thermal processors, the starting workspace is materially more specific than the old generic machine template.
• If the prompt does not match supported coverage strongly enough, the app should ask clarifying questions instead of pretending the structure is trustworthy.
• It does not guarantee the “correct” decomposition.
• It can still guess the wrong product family, wrong contradiction, or weak FR/DP seeds.
• You should treat the output as an editable first pass, not ground truth.

What The “RAG” Layer Really Is

The current retrieval layer is a small local JSON corpus plus token-overlap search.

It is not:

• a vector database
• a pgvector deployment
• Pinecone
• semantic retrieval at production quality

Right now it does this:

• tokenizes the query
• tokenizes each passage
• scores simple token overlap plus tag matches
• returns the top local passages, including source metadata when a passage came from an external mechanical-design reference

The current corpus now mixes:

• sourced summaries from NIST, MIT OpenCourseWare, Axiomatic Design Theory, and Stanford course material
• internal seeded notes for case-pattern and app-specific guidance

That is enough for seeded context and narration, but it is still a stub compared with a serious design-knowledge base.

What The LLM Does And Does Not Do

The LLM currently does:

• narrate module outputs in plain language
• optionally parse intake descriptions into JSON seeds

The LLM currently does not:

• own TRIZ matrix logic
• compute axiomatic scores
• compute weighted totals
• provide guaranteed-correct design decompositions
• act as a strong critic that systematically challenges every missing step

If Ollama is offline, the app still works, but it falls back to deterministic text and intake heuristics.

Important Limitations

• TRIZ is only the seeded 1-10 matrix, not the full 39 x 39 Altshuller matrix.
• Retrieval is local token-overlap search, not true vector RAG.
• Intake orchestration is a seeded parser, not a robust engineering reasoning engine.
• Machine content is stronger for the supported archetype packs, but arbitrary product classes still fall back to broader heuristics and should trigger clarification before analysis.
• Physical decomposition is heuristic and shallow.
• The morphology library is small and hand-seeded.
• The knowledge corpus is now source-backed in part, but it is still short summaries rather than a large engineering library or vector index.
• Concept scores are useful for comparison inside the prototype, but they are not validated engineering performance models.
• Session persistence is real, and event-to-event diffing exists, but there is still no branch-style replay or alternative-comparison workflow.
• Supabase support is wired, but local JSON storage is the default and the easiest path to verify locally.

Local Run

1. Bootstrap

.\scripts\bootstrap.ps1

2. Start Ollama

Default config expects:

http://127.0.0.1:11434
model: llama3.1:8b

You can override that in apps/api/.env.

3. Start the app

.\.venv\Scripts\Activate.ps1
npm run dev

That starts:

• FastAPI on http://127.0.0.1:8000
• Vite on http://127.0.0.1:5173

Quick Walkthrough

If you want one concrete run instead of reading the architecture, do this:

1. Start the app and open http://127.0.0.1:5173.
2. In the LLM Design Pilot at the top of the page, paste this into the prompt box:

A countertop coffee grinder that meters beans into burrs, grinds consistently, and reduces noise during daily use.

3. Click Infer workspace.
4. Watch the assistant thread respond with the inferred product setup and assumptions.
5. Check the inference provenance table. If the prompt was short or generic, the app will now flag the weak fields explicitly instead of silently hiding them.
6. If you want to override anything, use the manual editor underneath. That editor is the pilot override for product setup, flows, sub-functions, components, TRIZ inputs, and the FR/DP matrix.

If you do not want to type, use one of the built-in example buttons instead:

• Cordless Drill
• Coffee Grinder
• Insulin Pump

What happens next:

• the app creates a new audit session
• the intake orchestrator seeds a structured workspace from that description
• the assistant view shows what it inferred and which assumptions were made
• the provenance view shows which fields came from user input, LLM output, or deterministic family heuristics
• the manual editor fields are replaced with parsed values such as Countertop Coffee Grinder, Reduce coffee beans to a controlled particle size, multi-stage material flow, grinder-specific sub-functions, grinder components, a seeded TRIZ contradiction, and seeded FRs/DPs
• the backend immediately runs the normal deterministic modules on that parsed workspace

What you should then see on the right:

• a function tree with rows like receive coffee beans, meter beans to burrs, transmit torque to burrs, grind beans to target particle size, discharge grounds, regulate grind setting
• a physical decomposition and DSM for the seeded machine components
• a morphological chart populated from the library
• a TRIZ matrix with the active contradiction cell highlighted, plus the recommended principles from that cell
• an axiomatic design matrix with an initial classification
• a concept synthesis section with ranked concepts if no morphology gaps remain

If you turn Use morphology library off and run the same example, the morphological chart will show explicit GAP rows and concept scoring will be blocked. That is expected behavior in the current MVP.

If you only type a very short product name such as coffee grinder, the app will still generate a workspace, but it will also mark low-confidence fields and generic placeholders instead of pretending the decomposition is fully trustworthy.

Example Screen

This screenshot is from the live local app after a coffee-grinder intake run through the LLM Design Pilot:

Verification

Backend tests:

.\.venv\Scripts\python.exe -m pytest apps\api\tests

Frontend production build:

npm run build:web

At the time of the latest update:

• backend tests passed
• frontend build passed

External Knowledge Sources

The current corpus now includes paraphrased summaries from a small set of online mechanical-design sources. The active source list is documented in docs/mechanical-engineering-knowledge-sources.md.

API Surface

• GET /api/health
• GET /api/sessions
• POST /api/sessions
• GET /api/sessions/{session_id}
• POST /api/intake/orchestrate
• POST /api/modules/project-setup
• POST /api/modules/functional-decomposition
• POST /api/modules/physical-decomposition
• POST /api/modules/morphological-chart
• POST /api/modules/triz
• POST /api/modules/axiomatic-design
• POST /api/modules/concept-synthesis
• POST /api/workspace/analyze

Persistence

• Default persistence is local JSON at apps/api/.local/sessions.json
• Each module call writes an immutable decision event
• A session also stores the latest structured workspace and latest module outputs
• Optional Supabase support exists behind DIP_SUPABASE_URL and DIP_SUPABASE_SERVICE_ROLE_KEY

Example Of The Current Sweet Spot

The current seeded intake and morphology logic work best on products that fit one of these broad families:

• writing instruments
• hand tools
• dispensing devices
• generic machine systems

Within those families, the strongest seeded machine archetypes right now are:

• drills
• grinders
• conveyor sorters
• conveyors
• mixers
• thermal processing machines

Examples that currently run well in the local app include:

• mechanical pencil
• cordless drill
• coffee grinder
• insulin pump

Outside those seeded families, the app still produces a structured first pass, but the odds of generic or weak sub-functions go up.

What Is Not Implemented Yet

• full 39 x 39 TRIZ contradiction matrix
• vector-database-backed retrieval
• branch-style provenance replay and richer diff views across alternatives
• automatic derivation of trustworthy FR/DP structures from arbitrary products
• manual morphology path picking in the UI
• robust function-to-component assignment logic beyond the current heuristic matching
• session comparison across branches or alternatives

Repo Status

This repository currently contains a working local prototype with:

• a real frontend
• a real backend
• real local persistence
• real deterministic method engines
• a real intake orchestration endpoint

But several parts are still seeded, heuristic, or intentionally scoped down. The README is meant to describe that reality, not an eventual roadmap.