NGIE-AI Architecture Overview

Architecture snapshot: July 6, 2026
Operating model: Local, deterministic, file-based
AI APIs: Not used
Primary canonical dataset: knowledge/objects/*.json

What NGIE-AI Is Today

NGIE-AI is now a deterministic Business Knowledge Operating System that can ingest ecosystem websites, convert them into structured knowledge, build relationships, generate business intelligence, make rule-based recommendations, and produce client-ready ecosystem assessments without using AI APIs yet.

The platform is currently a collection of local command-line modules and generated files. It does not yet use autonomous agents, a database, vector search, or a dashboard.

Architecture at a Glance

Websites
   ↓
Extraction Pipeline
   ↓
Knowledge Objects
   ↓
Search + Review + Explorer
   ↓
Knowledge Graph
   ↓
Business Intelligence
   ↓
Decision Engine
   ↓
Ecosystem Assessment
   ↓
Future Client Products

The implemented assessment path also uses the Industry Solutions layer as a deterministic bridge between the Decision Engine and the Ecosystem Assessment:

Decision Engine
   ↓
Industry Solutions
   ↓
Ecosystem Assessment

Folder Flow

sources/
   ↓
knowledge/
   ↓
knowledge/objects/
   ↓
knowledge/relationships/     (logical layer; no physical folder currently)
   ↓
knowledge/graph/
   ↓
reports/
   ↓
reports/client-assessments/

The requested knowledge/relationships/ step is currently logical rather than physical. Relationship fields such as related_services, related_products, related_organizations, websites, tags, and keywords live in each canonical knowledge object. The graph builder materializes those relationships directly into knowledge/graph/edges.jsonl and knowledge/graph/graph.json.

Current Platform Summary

Platform measure	Current state
Website registry	6 active websites
Total website pages processed	137
Total website metadata files	137
Total canonical knowledge objects	137
Review status	29 approved, 100 pending, 3 needs revision, 5 rejected
Review quality signals	9 thin-content objects reviewed; 0 unresolved thin objects; 2 duplicate warnings resolved; 0 active duplicates
Knowledge Graph	859 nodes, 2,958 edges, 1 connected component, 0 orphan nodes, 0 dangling edges
Business Intelligence	6 organizations, 6 websites, 11 categories; 21.2% approved; not ready for AI reasoning
Decision Engine	6 deterministic organization profiles; recommendations remain human-review candidates
Industry Solutions bridge	6 deterministic industry blueprints; 1 design-ready, 3 prototype-ready, 2 evidence-required
Ecosystem Assessment	Operational CLI; JSON, Markdown, and valid PDF placeholder outputs
Assessment validation	1 sample assessment generated; 39/100 sample score; 17 approved supporting objects; automated test passing
Workflow Engine	3 allow-listed workflows; dry-run and audited execution supported
ChatGPT export	Preparation workflow ready; `conversations.json` is not currently present

Website Processing Detail

Website	Pages	Metadata	Queue or deferred URLs
`ellijayriverspace.com`	17	17	0
`eriverspace.org`	20	20	0
`foodtechsupply.com`	25	25	445
`giniinc.com`	25	25	8
`giniinc.tech`	25	25	183
`giniverse108.com`	25	25	425
Total	137	137	1,061

The giniinc.tech crawl uses an older report shape and records 183 URLs as remaining_queue; the other capped crawls record 878 URLs explicitly as deferred. Together they represent 1,061 URLs not processed in the capped runs.

Component Architecture

1. Website Source Registry

Purpose

Maintains the authoritative list of ecosystem websites and their organization, source type, industry, active state, and crawl priority.

Inputs

Manually maintained website and organization details.

Input files or folders

sources/websites.yaml

Outputs

Registry entries consumed by crawl and extraction commands.

Main scripts

No dedicated registry script.
scripts/crawl-website.mjs reads the registry.

Reports generated

No standalone registry report.

Connection to the next layer

Active registry entries identify the sites available to the Website Knowledge Extraction Pipeline.

Current status

Complete and operational for six active websites: GiNi Inc, GiNi Tech, eRiverSpace, Ellijay RiverSpace, Giniverse108, and FoodTechSupply.

2. Website Knowledge Extraction Pipeline

Purpose

Crawls registered websites, downloads pages, removes repeated layout content, preserves cleaned HTML, converts pages to Markdown, generates per-page metadata, and records crawl outcomes.

Inputs

sources/websites.yaml
A selected website key or URL.
Website HTML, robots information, and discovered links.

Input files or folders

sources/websites.yaml
sources/websites/

Outputs

For each site:

knowledge/<website-slug>/raw/*.html
knowledge/<website-slug>/cleaned/*.html
knowledge/<website-slug>/pages/*.md
knowledge/<website-slug>/metadata/*.json
knowledge/<website-slug>/reports/crawl-report.json
knowledge/<website-slug>/reports/crawl-report.md
knowledge/<website-slug>/robots.txt

Main scripts

scripts/crawl-website.mjs

Reports generated

knowledge/<website-slug>/reports/crawl-report.md
reports/giniinc-com-crawl-report.md
reports/eriverspace-crawl-report.md
reports/ellijayriverspace-crawl-report.md
reports/giniverse108-crawl-report.md
reports/foodtechsupply-crawl-report.md
reports/remaining-websites-extraction-summary.md

The initial GiNi Tech report remains under knowledge/giniinc-tech/reports/.

Connection to the next layer

Clean page Markdown and page metadata become the source records for the Website Knowledge Object Generator.

Current status

Operational. Six websites produced 137 Markdown pages and 137 metadata files with no recorded page failures. Page caps left 1,061 discovered URLs queued or deferred for later depth expansion.

3. ChatGPT Export Preparation Workflow

Purpose

Prepares a private, Git-excluded landing area and readiness check for a future official ChatGPT conversations.json export.

Inputs

A user-downloaded official OpenAI export.
sources/chatgpt/exports/conversations.json when available.

Input files or folders

sources/chatgpt/exports/
sources/chatgpt/raw/
sources/chatgpt/archive/

Outputs

Readiness message indicating whether the export exists.
Protected source folders and documentation placeholders.

Prepared folders include:

sources/chatgpt/cleaned/
sources/chatgpt/conversations/
sources/chatgpt/extracted/
sources/chatgpt/metadata/
sources/chatgpt/reports/
sources/chatgpt/logs/

Main scripts

scripts/import_chatgpt_export.py — safe presence check only.
scripts/import-chatgpt.mjs — later local import work exists, but the official private export has not been supplied or run.

Reports generated

sources/chatgpt/reports/README.md is the current report placeholder.

Connection to the next layer

When authorized and validated, imported conversations are intended to be normalized into the same knowledge-object schema used for websites.

Current status

Preparation complete. Privacy exclusions and .gitkeep placeholders are present. sources/chatgpt/exports/conversations.json is not currently present, so no official ChatGPT export has entered the canonical knowledge repository.

4. Website Knowledge Object Generator

Purpose

Converts extracted website Markdown and metadata into canonical, standardized JSON knowledge objects and category-oriented Markdown views.

Inputs

knowledge/<website-slug>/pages/*.md
knowledge/<website-slug>/metadata/*.json
config/metadata_schema.yaml
config/categories.yaml
config/knowledge_object_types.yaml

Outputs

knowledge/objects/*.json — canonical object store.
knowledge/<category>/*.md — category-oriented Markdown views.
knowledge/object-id-map.json — stable KN-000000 aliases.
knowledge/website-object-generation-manifest.json

The category folders include organizations, services, products, events, marketing, sales, operations, training, playbooks, policies, research, tourism, marketplace, nonprofit, technology, and innovation.

Main scripts

scripts/generate-website-knowledge-objects.mjs
scripts/classify-knowledge.mjs — supporting classification and derived-document utility.

Reports generated

reports/website-knowledge-object-generation-report.md
reports/website-knowledge-object-generation-report.json
reports/knowledge-classification-report.md
reports/knowledge-classification-report.json

Connection to the next layer

Canonical objects feed local search, review, exploration, graph construction, Business Intelligence, the Decision Engine, and assessments.

Current status

Operational. The canonical store contains 137 objects generated from 137 website pages with no missing required source metadata. The generator reported 9 thin-content warnings and 2 duplicate warnings; all have been explicitly resolved or reviewed by the review workflow.

Architecture note

knowledge/classification-index.json contains 322 derived classification documents. These are not the canonical object count. The authoritative object count remains the 137 JSON files in knowledge/objects/.

5. Local Knowledge Search

Purpose

Provides deterministic keyword search and weighted ranking across canonical knowledge fields without embeddings, vector search, a database, or an external service.

Inputs

knowledge/objects/*.json
Search terms supplied at the command line.

Outputs

Ranked terminal results with title, organization, category, source URL, summary, and match score.
Optional persisted deterministic index at knowledge/search-index.json.

Main scripts

scripts/search-knowledge.mjs — direct search across canonical objects.
scripts/build-search-index.mjs — builds the persisted classification search index.

Reports generated

reports/search-test-report.md
reports/knowledge-search-report.md
reports/knowledge-search-verification.md

Connection to the next layer

Search makes objects discoverable for human review and is reused by the Knowledge Explorer.

Current status

Operational. Direct CLI search reads the 137 canonical objects. The persisted search index currently contains 322 derived classification documents and 5,995 searchable tokens; this count must not be confused with canonical objects.

6. Knowledge Review Workflow

Purpose

Allows a human reviewer to inspect, approve, revise, reject, annotate, and assign confidence to canonical knowledge objects before downstream reliance.

Inputs

knowledge/objects/*.json
knowledge/object-id-map.json
Reviewer commands and notes.

Outputs

Updates these object fields:

review_status
reviewed_by
reviewed_at
review_notes
confidence_level

Main scripts

scripts/review-knowledge.mjs

Reports generated

reports/knowledge-review-status.md
reports/knowledge-review-sprint-1.md

Connection to the next layer

Review status becomes a trust gate for graph properties, BI readiness, Decision Engine recommendations, Industry Solutions evidence, and Ecosystem Assessment recommendations.

Current status

Operational. Current state: 29 approved, 100 pending, 3 needs revision, and 5 rejected. All 9 thin-content objects were reviewed; 2 duplicate warnings were resolved; no active duplicate warnings remain.

7. Knowledge Explorer

Purpose

Provides an interactive and one-shot CLI for repository search, filtering, object inspection, relationship exploration, and repository summaries.

Inputs

knowledge/objects/*.json
knowledge/object-id-map.json
User commands such as search, organization, website, category, tag, status, show, related, and summary.

Outputs

Interactive terminal views.
One-shot terminal results.
Stable object aliases when missing.

Main scripts

scripts/knowledge-explorer.mjs
Reuses exports from scripts/search-knowledge.mjs.

Reports generated

No standalone Explorer report; its output is interactive.

Connection to the next layer

The Explorer lets humans inspect canonical objects and their direct contextual relationships before or after graph generation.

Current status

Operational as a local CLI. It does not provide a browser interface or dashboard.

8. Knowledge Graph / Relationship Engine

Purpose

Materializes object provenance, classification, organization, website, tag, keyword, service, and product relationships as a local property graph.

Inputs

knowledge/objects/*.json
knowledge/object-id-map.json
config/knowledge_graph_schema.yaml

Outputs

knowledge/graph/graph.json
knowledge/graph/nodes.jsonl
knowledge/graph/edges.jsonl
knowledge/graph/metrics.json

Main scripts

scripts/build-knowledge-graph.mjs
scripts/knowledge-graph.mjs

Reports generated

reports/knowledge-graph-report.md

Connection to the next layer

Graph connectivity and relationships feed Business Intelligence, Decision Engine profiles, Industry Solutions evidence ranking, and assessment evidence ranking.

Current status

Operational and structurally valid: 859 nodes, 2,958 edges, one connected component, no orphan nodes, and no dangling edges.

9. Business Intelligence Engine

Purpose

Aggregates repository quality, category coverage, organization metrics, graph relationships, approval readiness, and opportunity signals into deterministic intelligence datasets.

Inputs

knowledge/objects/*.json
knowledge/graph/graph.json
knowledge/object-id-map.json
config/business_intelligence.yaml

Outputs

intelligence/business-intelligence.json
intelligence/organization-profiles.json
intelligence/category-profiles.json
intelligence/opportunity-signals.json
intelligence/quality-signals.json
intelligence/organization-metrics.csv
intelligence/category-coverage.csv

Main scripts

scripts/build-business-intelligence.mjs
scripts/business-intelligence.mjs

Reports generated

reports/business-intelligence-report.md

Connection to the next layer

BI metrics and quality gates become inputs to the Decision Engine and are carried into assessment platform context.

Current status

Operational for 137 objects, 6 organizations, 6 websites, and 11 represented categories. Approval coverage is 21.2%, so ready_for_ai_reasoning remains false.

10. Decision Engine

Purpose

Transforms knowledge objects, graph relationships, and Business Intelligence into deterministic organization profiles, gaps, training needs, marketplace opportunities, and recommendation candidates.

Inputs

knowledge/objects/*.json
knowledge/graph/graph.json
intelligence/business-intelligence.json
knowledge/object-id-map.json
config/decision_engine.yaml

Outputs

reports/decision-engine/<organization>.json
reports/decision-engine/<organization>.md
reports/decision-engine/decision-engine-summary.json
reports/decision-engine/index.md

Main scripts

scripts/build-decision-engine.mjs
scripts/decision-engine.mjs

Reports generated

Six organization profile reports plus the Decision Engine index.

Connection to the next layer

Decision profiles determine industry alignment, maturity, readiness, gaps, and recommendation context. The Industry Solutions bridge turns those profiles into reusable industry blueprints consumed by the Ecosystem Assessment.

Current status

Operational. Six organization profiles cover tourism and hospitality, foodservice supply, technology services, professional services, retail marketplace, and nonprofit innovation. Business size remains undetermined for these repository-derived profiles because reliable employee or financial data is absent. Recommendations require human review.

Implemented Decision-to-Assessment Bridge: Industry Solutions

Purpose

Packages approved evidence and Decision Engine profiles into six industry-specific solution blueprints.

Inputs

Canonical objects, Knowledge Graph, BI outputs, and Decision Engine profiles.
config/industry_solutions.json

Outputs

reports/industry-solutions/*.json
reports/industry-solutions/*.md
reports/industry-solutions/industry-solutions-summary.json
reports/industry-solutions/index.md

Main scripts

scripts/build-industry-solutions.mjs
scripts/industry-solutions.mjs

Current status

Operational. Six blueprints exist: one is design_ready, three are prototype_ready, and two are evidence_required. All explicitly set deployment to false.

11. NGIE Ecosystem Assessment Module

Purpose

Creates a client-facing business assessment from declared client inputs and existing deterministic platform evidence.

Inputs

A client JSON file based on templates/client_assessment_input.json.
config/ecosystem_assessment.json
knowledge/objects/*.json
knowledge/object-id-map.json
knowledge/graph/graph.json
intelligence/business-intelligence.json
reports/decision-engine/*.json
reports/industry-solutions/*.json

Client inputs include business name, industry, employees, location, website, current technology, marketing presence, goals, operational challenges, growth challenges, and desired outcomes.

Outputs

For each assessed business:

reports/client-assessments/<business-slug>/assessment.json
reports/client-assessments/<business-slug>/assessment.md
reports/client-assessments/<business-slug>/assessment.pdf

The assessment includes an executive summary, business profile, ten-category capability assessment, gap analysis, recommended services, products, training, AI modules, partners, a 90-day roadmap, a one-year roadmap, and a supporting knowledge-object index.

Main scripts

scripts/generate-ecosystem-assessment.mjs

Reports generated

reports/client-assessments/sample-north-georgia-business/assessment.json
reports/client-assessments/sample-north-georgia-business/assessment.md
reports/client-assessments/sample-north-georgia-business/assessment.pdf

Connection to the next layer

Assessment outputs are the first reusable client-product artifacts. Future client portals, polished reports, dashboards, and governed AI reasoning can consume the structured assessment JSON.

Current status

Operational and tested. The sample produces all three required formats, scores ten assessment categories, and references 17 approved knowledge objects. The PDF is intentionally a valid one-page placeholder; JSON and Markdown remain authoritative. No deployment, purchasing, outreach, or automated action is authorized.

12. Workflow Engine

Purpose

Orchestrates existing NGIE-AI scripts in declared dependency order with validation, fail-fast execution, dry runs, timeouts, output checks, and auditable run records.

Inputs

config/workflows.json
Existing platform scripts and their required files.
An optional client assessment input for the client-assessment workflow.

Outputs

reports/workflows/runs/<run-id>/workflow-run.json
reports/workflows/runs/<run-id>/workflow-run.md
Per-step log files.

Main scripts

scripts/workflow-engine.mjs

Reports generated

One JSON and Markdown audit report per workflow run.
One local log per executed step.

Connection to the next layer

The engine provides a reproducible orchestration boundary around platform refresh, validation, and client assessment generation. A future dashboard can invoke these same workflows without duplicating pipeline logic.

Current status

Operational and tested. Three workflows are registered: platform-refresh, platform-validation, and client-assessment. Only allow-listed Node.js scripts can run; shell commands, external actions, and AI APIs are disabled.

Trust and Governance Flow

Extracted content
   ↓
Canonical object with provenance
   ↓
Human review status
   ↓
Graph and BI quality signals
   ↓
Rule-based recommendation
   ↓
Supporting knowledge-object references
   ↓
Human validation before action

The trust boundary is the canonical object review state. Downstream modules may analyze all objects for coverage and quality, but Industry Solutions and Ecosystem Assessment recommendations use approved evidence.

Known Architecture Boundaries

The platform is local and file-based; concurrent multi-user editing is not managed.
knowledge/objects/ is canonical. Category folders and the 322-document classification index are derived views.
knowledge/relationships/ does not physically exist; relationships are embedded in objects and materialized in the graph.
The persisted classification search index and canonical direct-search path have different document counts and should be reconciled during architecture validation.
Only 21.2% of canonical objects are approved, so BI correctly blocks AI-reasoning readiness.
The assessment is a CLI application, not a dashboard.
The Workflow Engine orchestrates local modules but does not provide scheduling, distributed execution, or multi-user locking.
The PDF is a placeholder, not the final client presentation design.
Website crawls were capped; 1,061 discovered URLs remain queued or deferred.
The official ChatGPT export has not been imported.
No database, vector store, AI API, autonomous agent, or production deployment layer exists.

Recommended Next Build

Architecture validation report — verify canonical-versus-derived datasets, refresh order, dependency contracts, stale artifacts, and end-to-end reproducibility.
Test assessment using one sample business — preserve the current sample as a repeatable acceptance test and conduct a human content review.
Assessment report template improvements — turn the placeholder PDF into a polished, branded client document after content validation.
Simple local dashboard — expose repository health, review queues, graph metrics, BI profiles, and assessment runs without changing the deterministic core.
AI reasoning layer after validation — add governed reasoning only after architecture, evidence quality, privacy, and assessment outputs are validated.

No new feature should bypass the review gate or treat derived classification documents as additional canonical knowledge objects.