NODEDC_1C/docs/ARCH/11 - architecture_turnaround/01 - project_architecture_baseline_map.md

01 - Project Architecture Baseline Map

Purpose

This note is the compact execution-oriented map of the current project.

It is not a market review and not a historical report. It answers:

• what the main subsystems are;
• where the assistant runtime really starts and ends;
• what already acts as architecture, not as incidental code;
• where the main structural debt sits.

System Map

1. 1C Acquisition And Probe Layer

Main areas:

• odata_probe/
• scripts/* probe and verification scripts

Role:

• verify read-only access viability;
• inspect published 1C entity sets and links;
• produce source-level readiness for higher layers.

This is a prerequisite layer, not the assistant runtime itself.

2. Canonical And Analytical Data Layer

Main areas:

• canonical_layer/
• data/
• logs/

Current runtime entry:

• canonical_layer/app.py

Role:

• expose normalized read-only data services;
• refresh and maintain the canonical store;
• run feature engine;
• run risk engine.

This layer is the project's data foundation.

3. LLM Backend And Assistant Runtime

Main area:

• llm_normalizer/backend/

Current server entry:

• server.ts

Role:

• provider gateway;
• normalizer runtime;
• assistant runtime;
• eval runtime;
• autorun runtime;
• session persistence.

This is the architectural center of the interactive product.

4. Domain Orchestration And Acceptance Loop

Main areas:

• .codex/
• docs/orchestration/active_domain_contract.json
• artifacts/domain_runs/

Role:

• define the current active domain pack;
• execute scenario-based hardening;
• store machine-readable before/after artifacts;
• turn user runs into acceptance and repair targets.

This is a first-class quality contour, not auxiliary documentation.

5. Experimental Routing / Benchmark Contour

Main area:

• router/

Role:

• route-selection experiments;
• store-sufficiency heuristics;
• benchmark and validation support via Python scripts.

Important:

• this contour is not the current source of truth for the production assistant runtime;
• current production routing lives in the TypeScript assistant stack.

Assistant Runtime Map

The assistant runtime currently has these working layers:

1. provider/model gateway
2. living router
3. address orchestration runtime
4. exact execution lane
5. coverage / evidence / grounding
6. answer policy / packaging / debug
7. session memory / navigation state

Provider / Model Gateway

Current main entry:

• openaiResponsesClient.ts

Current shape:

• pragmatic two-mode provider layer: openai and local

This layer is functional, but future-fragile if hybrid execution semantics grow.

Living Router

Current main entry:

• assistantService.ts

Current top-level modes:

• address_data
• assistant_data_scope
• chat

This is where the system decides which runtime contour gets control.

Address Orchestration Runtime

Current main entry:

• assistantAddressOrchestrationRuntimeAdapter.ts

Current responsibilities:

• predecompose;
• effective message normalization;
• carryover resolution;
• rewrite protection;
• continuation contract assembly;
• address runtime metadata.

Exact Execution Lane

Current main areas:

• addressQueryService.ts
• addressIntentResolver.ts
• addressFilterExtractor.ts
• addressRecipeCatalog.ts
• decomposeStage.ts
• composeStage.ts

This lane already acts as a real exact-data runtime, not as generic chat assistance.

Coverage / Evidence / Grounding

Current main areas:

• assistantCoverageGrounding.ts
• assistantClaimBoundEvidence.ts
• assistantDataLayer.ts

This layer already exists in code, even if it has not yet been named strongly enough in architecture docs.

Answer Policy / Packaging / Debug

Current main areas:

• answerComposer.ts
• assistantAnswerPackageBuilder.ts
• assistantDebugPayloadAssembler.ts

This layer should own answer shape, not truth determination.

Session Memory / Navigation State

Current main areas:

• assistantSessionStore.ts
• addressNavigationState.ts
• investigationState.ts

This layer is one of the strongest parts of the architecture today.

First-Class Runtime Artifacts Already Present

The following should be treated as first-class architectural artifacts, not helper byproducts:

• dialogContinuationContractV2
• result_set
• focus_object
• date_scope
• organization_scope
• coverage report
• grounding check
• evidence bundle
• scenario manifest
• scenario state
• baseline_turn / rerun_turn artifacts

Structural Debt

The main structural debt is concentrated in oversized modules with mixed responsibilities:

• assistantService.ts
• composeStage.ts
• answerComposer.ts
• addressQueryService.ts
• assistantDataLayer.ts

This indicates the following problem:

• the system already has the right layers;
• but too many of those layers are still implemented as tightly coupled code inside a few large files.

Baseline Constraints

Any architectural turnaround must preserve:

• AddressQueryService as exact lane;
• structured navigation state;
• continuation contract semantics;
• selected-object continuity;
• limited-mode truthfulness;
• scenario-based acceptance.

Baseline Diagnosis

The project is not missing architecture.

The project already has architecture, but it is still expressed too much through:

• god services;
• implicit workflow;
• heuristic branching;
• mixed policy/state/answer concerns.

That is the baseline condition that the rest of this package is designed to address.