Product-System / LCA Architecture Workspace

Repository orientation. This file owns no authority; it points to the docs and routes that do. See "What owns what" below.

This repository currently contains a carbon/PCF runtime slice: supplier emission submissions move through review, admission, and rollup into accepted, disclosable climate-change results, with a frontend that projects backend authority.

That runtime is the current shape, not the architecture root. The direction-facing read is product-system / LCA: carbon is one impact-result family, and a PCF is one product-level claim under a declared product system, functional unit, boundary, method, data basis, assurance, and disclosure context.

At that altitude, the repository is read as an impact-result claim governance spine. It takes in claims from producers, reviews and accepts them, reuses them, and rolls them up; it does not make impact computation itself the root responsibility.

Current LCA working surfaces now cover the bounded openLCA/USLCI path around that spine: reference-card staging, accepted mapping decisions, working-set export, provider-closure/admission checks, internal-model adaptation, matrix-engine run/replay/claim landing, climate/GWP promotion into the existing AcceptedEmission authority path, and demand worklists for unresolved definitions, units, factors, and provider occurrences. These surfaces are current runtime contacts and execution evidence, not a new LCA root or generic accepted-impact authority.

The current carbon-runtime spine is:

DataRequest -> SubmissionPackage -> AnalysisRun
-> Normalization / QualitySignal / ReferenceResolutionTask -> IssueThread
-> ReviewDecision -> AcceptedEmission -> RollupSnapshotItem -> RollupSnapshot

The product-system / LCA direction is design-stage planning, not runtime authority. Use the routes below to separate current contracts from direction-facing planning.

Repository Layout

Path	What
backend/	FastAPI services, routes, database models, policies, and tests
frontend/	UI projecting backend authority; no separate wire-contract authority
docs/	Documentation; start at docs/index.md
tools/	Policy checkers (check_*) and observational reports (report_*)
scripts/	Cross-platform entry points such as scripts/backend_test.py
catalogs/	Reference catalog data

Running Checks

Backend tests go through one entry point so local runs, CI, and agent runs use the same dependency path:

python scripts/backend_test.py
python scripts/backend_test.py <pytest-target> -q

AGENTS.md owns test, lint, and CI-policy instructions. This README only names the canonical backend entry point.

Where To Read Next

You want	Go to
How the docs are organized	docs/index.md
Working in the repo: tests, CI, policy gates	AGENTS.md
Current runtime architecture authority	docs/architecture/README.md
Backend service ownership and LCA service spine	docs/architecture/maps/backend-service-surface-ownership-map.md
Where architecture direction is emerging	docs/active-architecture-direction/README.md
Product-system / LCA planning route	docs/product-system-architecture/README.md

What Owns What

This README is orientation only. It does not define runtime contracts, document authority, candidate lifecycle state, or test/CI policy. When it disagrees with an owning surface, the owning surface wins.

• Runtime contracts and current architecture: docs/architecture/**
• Document authority and routing: docs/index.md, docs/architecture/governance/**
• Active direction and current-runtime reality contact: docs/active-architecture-direction/**
• Product-system / LCA planning memory and evidence: docs/product-system-architecture/knowledge/**, docs/product-system-architecture/evidence/**
• Test, lint, and CI policy: AGENTS.md