# 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](/x:/1C/NDC_1C/canonical_layer/app.py:1)

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](/x:/1C/NDC_1C/llm_normalizer/backend/src/server.ts:1)

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](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/openaiResponsesClient.ts:1)

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](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:4248)

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](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantAddressOrchestrationRuntimeAdapter.ts:1)

Current responsibilities:

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

### Exact Execution Lane

Current main areas:

- [addressQueryService.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressQueryService.ts:1)
- [addressIntentResolver.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressIntentResolver.ts:1)
- [addressFilterExtractor.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressFilterExtractor.ts:1)
- [addressRecipeCatalog.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressRecipeCatalog.ts:1)
- [decomposeStage.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/address_runtime/decomposeStage.ts:1325)
- [composeStage.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/address_runtime/composeStage.ts:1)

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

### Coverage / Evidence / Grounding

Current main areas:

- [assistantCoverageGrounding.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantCoverageGrounding.ts:1)
- [assistantClaimBoundEvidence.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantClaimBoundEvidence.ts:1)
- [assistantDataLayer.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantDataLayer.ts:1)

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](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/answerComposer.ts:1)
- [assistantAnswerPackageBuilder.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantAnswerPackageBuilder.ts:1)
- [assistantDebugPayloadAssembler.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantDebugPayloadAssembler.ts:1)

This layer should own answer shape, not truth determination.

### Session Memory / Navigation State

Current main areas:

- [assistantSessionStore.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantSessionStore.ts:1)
- [addressNavigationState.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressNavigationState.ts:329)
- [investigationState.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/investigationState.ts:1)

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.