# Architecture

## Goal

Replace the operational experience of `AS0558844.xlsm` with a functional SPA
and REST API while preserving traceability to the workbook, VBA procedures and
the Neo4j knowledge graph.

## Layers

```text
React workspaces
  -> typed API client
    -> FastAPI routes
      -> risk reporting service
        -> thread-safe in-memory repository
```

Traceability is a cross-cutting catalog exposed through
`GET /api/traceability/{workspace}`. It links each workspace to worksheets,
ranges, epics, entry points, flows, business rules, VBA procedures, logical
data elements and verification cases.

## Workspaces

1. Overview: `Dashboard` and `Version Control`.
2. Reporting Controls: `Worksheet Controls`.
3. Source Data Hub: the eight staging/source worksheets.
4. Monthly Comparison: `Sched 2.1- Monthly Comparat`.
5. Previous Month: `Previous Month`.
6. Variance Analysis: `Variance Analysis`.
7. Reconciliation Controls: `Controls`.
8. Adjustments & Export: VBA `UserForm1`, `UserForm2` and reporting schedule.

## State and persistence

The target strategy is intentionally in-memory. A process restart restores the
workbook-aligned seed state. Mutating operations are serialized by the
repository lock and recorded in an in-memory audit trail.

## Evidence boundary

The workbook and graph are authoritative evidence. The source workbook is never
modified. Export creates metadata describing the target output and reporting
range. Because graph extraction reached formula relationship caps, detailed
formula lineage beyond the mapped fields is not asserted.

