Add engineering architecture docs

docs/architecture/engineering-ontology-v1.md

@@ -0,0 +1,250 @@
+# Engineering Ontology V1
+
+## Purpose
+
+Define the first practical engineering ontology that can sit on top of AtoCore and represent a real engineering project as structured knowledge.
+
+This ontology is intended to be:
+- useful to machines
+- inspectable by humans through derived views
+- aligned with AtoCore trust / provenance rules
+- expandable across mechanical, FEM, electrical, software, manufacturing, and operations
+
+## Goal
+
+Represent a project as a **system of objects and relationships**, not as a pile of notes.
+
+The ontology should support queries such as:
+- what is this subsystem?
+- what requirements does this component satisfy?
+- what result validates this claim?
+- what changed recently?
+- what interfaces are affected by a design change?
+- what is active vs superseded?
+
+## Object Families
+
+### Project structure
+- Project
+- System
+- Subsystem
+- Assembly
+- Component
+- Interface
+
+### Intent / design logic
+- Requirement
+- Constraint
+- Assumption
+- Decision
+- Rationale
+- Risk
+- Issue
+- Open Question
+- Change Request
+
+### Physical / technical definition
+- Material
+- Parameter
+- Equation
+- Configuration
+- Geometry Artifact
+- CAD Artifact
+- Tolerance
+- Operating Mode
+
+### Analysis / validation
+- Analysis Model
+- Load Case
+- Boundary Condition
+- Solver Setup
+- Result
+- Validation Claim
+- Test
+- Correlation Record
+
+### Manufacturing / delivery
+- Manufacturing Process
+- Vendor
+- BOM Item
+- Part Number
+- Assembly Procedure
+- Inspection Step
+- Cost Driver
+
+### Software / controls / electrical
+- Software Module
+- Control Function
+- State Machine
+- Signal
+- Sensor
+- Actuator
+- Electrical Interface
+- Firmware Artifact
+
+### Evidence / provenance
+- Source Document
+- Transcript Segment
+- Image / Screenshot
+- Session
+- Report
+- External Reference
+- Generated Summary
+
+## Minimum Viable V1 Scope
+
+Initial implementation should start with:
+- Project
+- Subsystem
+- Component
+- Requirement
+- Constraint
+- Decision
+- Material
+- Parameter
+- Analysis Model
+- Result
+- Validation Claim
+- Artifact
+
+This is enough to represent meaningful project state without trying to model everything immediately.
+
+## Core Relationship Types
+
+### Structural
+- `CONTAINS`
+- `PART_OF`
+- `INTERFACES_WITH`
+
+### Intent / logic
+- `SATISFIES`
+- `CONSTRAINED_BY`
+- `BASED_ON_ASSUMPTION`
+- `AFFECTED_BY_DECISION`
+- `SUPERSEDES`
+
+### Validation
+- `ANALYZED_BY`
+- `VALIDATED_BY`
+- `SUPPORTS`
+- `CONFLICTS_WITH`
+- `DEPENDS_ON`
+
+### Artifact / provenance
+- `DESCRIBED_BY`
+- `UPDATED_BY_SESSION`
+- `EVIDENCED_BY`
+- `SUMMARIZED_IN`
+
+## Example Statements
+
+- `Subsystem:Lateral Support CONTAINS Component:Pivot Pin`
+- `Component:Pivot Pin CONSTRAINED_BY Requirement:low lateral friction`
+- `Decision:Use GF-PTFE pad AFFECTS Subsystem:Lateral Support`
+- `AnalysisModel:M1 static model ANALYZES Subsystem:Reference Frame`
+- `Result:deflection case 03 SUPPORTS ValidationClaim:vertical stiffness acceptable`
+- `Artifact:NX assembly DESCRIBES Component:Reference Frame`
+- `Session:gen-004 UPDATED_BY_SESSION Component:Vertical Support`
+
+## Shared Required Fields
+
+Every major object should support fields equivalent to:
+- `id`
+- `type`
+- `name`
+- `project_id`
+- `status`
+- `confidence`
+- `source_refs`
+- `created_at`
+- `updated_at`
+- `notes` (optional)
+
+## Suggested Status Lifecycle
+
+For objects and claims:
+- `candidate`
+- `active`
+- `superseded`
+- `invalid`
+- `needs_review`
+
+## Trust Rules
+
+1. An object may exist before it becomes trusted.
+2. A generated markdown summary is not canonical truth by default.
+3. If evidence conflicts, prefer:
+   1. trusted current project state
+   2. validated structured records
+   3. reviewed derived synthesis
+   4. raw evidence
+   5. historical notes
+4. Conflicts should be surfaced, not silently blended.
+
+## Mapping to the Existing Knowledge Base System
+
+### KB-CAD can map to
+- System
+- Subsystem
+- Component
+- Material
+- Decision
+- Constraint
+- Artifact
+
+### KB-FEM can map to
+- Analysis Model
+- Load Case
+- Boundary Condition
+- Result
+- Validation Claim
+- Correlation Record
+
+### Session generations can map to
+- Session
+- Generated Summary
+- object update history
+- provenance events
+
+## Human Mirror Possibilities
+
+Once the ontology exists, AtoCore can generate pages such as:
+- project overview
+- subsystem page
+- component page
+- decision log
+- validation summary
+- requirement trace page
+
+These should remain **derived representations** of structured state.
+
+## Recommended V1 Deliverables
+
+1. minimal typed object registry
+2. minimal typed relationship registry
+3. evidence-linking support
+4. practical query support for:
+   - component summary
+   - subsystem current state
+   - requirement coverage
+   - result-to-claim mapping
+   - decision history
+
+## What Not To Do In V1
+
+- do not model every engineering concept immediately
+- do not build a giant graph with no practical queries
+- do not collapse structured objects back into only markdown
+- do not let generated prose outrank structured truth
+- do not auto-promote trusted state too aggressively
+
+## Summary
+
+Ontology V1 should be:
+- small enough to implement
+- rich enough to be useful
+- aligned with AtoCore trust philosophy
+- capable of absorbing the existing engineering Knowledge Base work
+
+The first goal is not to model everything.
+The first goal is to represent enough of a real project that AtoCore can reason over structure, not just notes.