Skip to content

architecture.md

Latest commit

 

History

History
119 lines (98 loc) · 4.96 KB

architecture.md

File metadata and controls

119 lines (98 loc) · 4.96 KB
Raw

Architecture

A proof of concept of the EKG-based DFAM design process model (Chen et al., Machines 2025, 13, 112). The system builds an Event Knowledge Graph for the intake-system case study, reasons over it, scores manufacturability, and visualizes the whole process.

Capability map

Capability Owner module Paper reference
Domain seeding backend/data/intake_system.yaml + app/domain/ Case study, Sec. 4
EKG construction app/graph/ekg_builder.py Algorithm 2, Sec. 3.4
Causality reasoning app/graph/reasoning.py Algorithm 1, Sec. 3.3
Manufacturability evaluation app/evaluation/scoring.py VDI, Eq. 1-2, Tables 1-2
Persistence / exploration app/graph/neo4j_client.py + Neo4j Sec. 3.4 (Neo4j)
Orchestration / API app/services.py + app/api/ -
Visualization frontend/ (React + Cytoscape) Figs. 3, 9-12

Component view

flowchart LR
    Yaml["intake_system.yaml"]
    subgraph backend [FastAPI backend]
        Domain["domain (models + seed)"]
        Builder["EKGBuilder (Algo 2)"]
        Reason["reasoning (Algo 1)"]
        Score["scoring (VDI, Eq 1-2)"]
        Service["EKGService"]
        API["REST API"]
    end
    Neo[("Neo4j")]
    subgraph frontend [React + Cytoscape]
        UI["Graph / Timeline / Scores"]
    end

    Yaml --> Domain --> Builder --> Service
    Reason --> Service
    Score --> Service
    Service --> Neo
    Service --> API --> UI
Loading

Layering and boundaries

  • Domain layer (app/domain/): pure Pydantic models and the YAML loader. No I/O beyond reading the seed. Single source of truth for the case-study knowledge.
  • Engine layer (app/graph/, app/evaluation/): pure, deterministic, fully unit-tested. The EKGBuilder produces an in-memory EKG (nodes, edges, snapshots); reasoning and scoring operate on it. No web framework imports.
  • Persistence adapter (app/graph/neo4j_client.py): the only Neo4j-aware module. Static labels/relationship types keep Cypher injection-safe (no APOC needed).
  • Service layer (app/services.py): orchestrates load -> build -> persist -> reason -> evaluate and holds the in-memory EKG as the source of truth.
  • API layer (app/api/): thin FastAPI controllers + the shared response schema (schemas.py), mirrored in the frontend as frontend/src/types.ts.

The in-memory EKG is the source of truth; Neo4j is a mirror for persistence and visual exploration in the Neo4j Browser. This keeps the engine fast and testable without a database and makes the whole API resilient when Neo4j is unavailable.

Request / build flow

sequenceDiagram
    participant UI as Frontend
    participant API as FastAPI
    participant S as EKGService
    participant B as EKGBuilder
    participant N as Neo4j

    UI->>API: POST /api/ekg/build
    API->>S: build()
    S->>B: build(domain, capability_scores)
    B-->>S: EKG (nodes, edges, snapshots)
    S->>N: sync_graph()  (best-effort)
    S-->>API: BuildResult
    UI->>API: GET /api/ekg/snapshots  (replay)
    UI->>API: POST /api/reasoning/run (stability + achievability)
    UI->>API: GET /api/evaluation/scores (Tables 1-2)
Loading

API surface

All under /api:

  • GET /health - status + Neo4j connectivity + whether the EKG is built.
  • POST /ekg/build - run Algorithm 2; returns node/edge/snapshot counts.
  • GET /ekg/graph - current EKG (nodes + edges); carries stability after reasoning.
  • GET /ekg/snapshots - cumulative graph after each event, for chronological replay.
  • GET /process/steps - the six design-process events (Figure 3).
  • POST /reasoning/run - Algorithm 1: node stability + achievability inferences.
  • GET /evaluation/scores - Table 2 (per-metric average + sample std).
  • GET /evaluation/realization - Table 1 (function x AM-capability matrix).
  • GET /comparison - Table 3 (vs prior methods).

Technology choices

  • Neo4j 5 (Community) - matches the paper; runs in Docker so no local Java is needed.
  • FastAPI + Pydantic v2 - typed, self-documenting (/docs), minimal boilerplate.
  • React + Vite + TypeScript + Cytoscape.js + Recharts - boring, well-understood UI stack; Cytoscape is purpose-built for graph rendering.
  • Deterministic reasoning - the relationship-aware mechanism is implemented as an explainable weighted information-flow rather than a trained GAT (documented in paper-mapping.md), which keeps the PoC reproducible and dependency-light.

Deployment

docker-compose.yml runs three services: neo4j, backend, frontend (nginx serving the built SPA and proxying /api to the backend). Host ports are configurable via .env (BACKEND_PORT, FRONTEND_PORT) to avoid clashes with other local services.

Testing strategy

  • Engines are unit-tested with no external dependencies (make test).
  • Tables 1-2 reproduction is asserted directly against the published numbers.
  • A Neo4j round-trip integration test runs only with a live database (make test-integration, gated by RUN_NEO4J_TESTS=1).