# Engineering Knowledge Hybrid Architecture

## Purpose

This note defines how **AtoCore** can evolve into the machine foundation for a **living engineering project knowledge system** while remaining aligned with core AtoCore philosophy.

AtoCore remains:
- the trust engine
- the memory/context engine
- the retrieval/context assembly layer
- the runtime-facing augmentation layer

It does **not** become a generic wiki app or a PLM clone.

## Core Architectural Thesis

AtoCore should act as the **machine truth / context / memory substrate** for project knowledge systems.

That substrate can then support:
- engineering knowledge accumulation
- human-readable mirrors
- OpenClaw augmentation
- future engineering copilots
- project traceability across design, analysis, manufacturing, and operations

## Layer Model

### Layer 0 — Raw Artifact Layer
Examples:
- CAD exports
- FEM exports
- videos / transcripts
- screenshots
- PDFs
- source code
- spreadsheets
- reports
- test data

### Layer 1 — AtoCore Core Machine Layer
Canonical machine substrate.

Contains:
- source registry
- source chunks
- embeddings / vector retrieval
- structured memory
- trusted project state
- entity and relationship stores
- provenance and confidence metadata
- interactions / retrieval logs / context packs

### Layer 2 — Engineering Knowledge Layer
Domain-specific project model built on top of AtoCore.

Represents typed engineering objects such as:
- Project
- System
- Subsystem
- Component
- Interface
- Requirement
- Constraint
- Assumption
- Decision
- Material
- Parameter
- Equation
- Analysis Model
- Result
- Validation Claim
- Manufacturing Process
- Test
- Software Module
- Vendor
- Artifact

### Layer 3 — Human Mirror
Derived human-readable support surface.

Examples:
- project overview
- current state
- subsystem pages
- component pages
- decision log
- validation summary
- timeline
- open questions / risks

This layer is **derived** from structured state and approved synthesis. It is not canonical machine truth.

### Layer 4 — Runtime / Clients
Consumers such as:
- OpenClaw
- CLI tools
- dashboards
- future IDE integrations
- engineering copilots
- reporting systems
- Atomizer / optimization tooling

## Non-Negotiable Rule

**Human-readable pages are support artifacts. They are not the primary machine truth layer.**

Runtime trust order should remain:
1. trusted current project state
2. validated structured records
3. selected reviewed synthesis
4. retrieved source evidence
5. historical / low-confidence material

## Responsibilities

### AtoCore core owns
- memory CRUD
- trusted project state CRUD
- retrieval orchestration
- context assembly
- provenance
- confidence / status
- conflict flags
- runtime APIs

### Engineering Knowledge Layer owns
- engineering object taxonomy
- engineering relationships
- domain adapters
- project-specific interpretation logic
- design / analysis / manufacturing / operations linkage

### Human Mirror owns
- readability
- navigation
- overview pages
- subsystem summaries
- decision digests
- human inspection / audit comfort

## Update Model

New artifacts should not directly overwrite trusted state.

Recommended update flow:
1. ingest source
2. parse / chunk / register artifact
3. extract candidate objects / claims / relationships
4. compare against current trusted state
5. flag conflicts or supersessions
6. promote updates only under explicit rules
7. regenerate affected human-readable pages
8. log history and provenance

## Integration with Existing Knowledge Base System

The existing engineering Knowledge Base project can be treated as the first major domain adapter.

Bridge targets include:
- KB-CAD component and architecture pages
- KB-FEM models / results / validation pages
- generation history
- images / transcripts / session captures

AtoCore should absorb the structured value of that system, not replace it with plain retrieval.

## Suggested First Implementation Scope

1. stabilize current AtoCore core behavior
2. define engineering ontology v1
3. add minimal entity / relationship support
4. create a Knowledge Base bridge for existing project structures
5. generate Human Mirror v1 pages:
   - overview
   - current state
   - decision log
   - subsystem summary
6. add engineering-aware context assembly for OpenClaw

## Why This Is Aligned With AtoCore Philosophy

This architecture preserves the original core ideas:
- owned memory layer
- owned context assembly
- machine-human separation
- provenance and trust clarity
- portability across runtimes
- robustness before sophistication

## Long-Range Outcome

AtoCore can become the substrate for a **knowledge twin** of an engineering project:
- structure
- intent
- rationale
- validation
- manufacturing impact
- operational behavior
- change history
- evidence traceability

That is significantly more powerful than either:
- a generic wiki
- plain document RAG
- an assistant with only chat memory