docs(scope): fill in SCOPE.md — resolves C-30 staleness
Replace the unfilled template with the umbrella's actual boundary: app/viewer/session + anchoring/evidence/binders in scope; headless ingest (evidence-source) and contracts (citation-engine) out of scope. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
89e6236554
commit
cf57a9bb50
1 changed files with 50 additions and 66 deletions
116
SCOPE.md
116
SCOPE.md
|
|
@ -8,130 +8,114 @@
|
|||
|
||||
## One-liner
|
||||
|
||||
<!-- Describe the purpose of this repository in one precise sentence. -->
|
||||
<!-- Example: "Provides a lightweight event router for Kubernetes-native systems." -->
|
||||
Document-centered evidence workspace — the umbrella app that lets a user open
|
||||
documents, capture selections as durable citations, and organize them into
|
||||
evidence sets and binders.
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
|
||||
<!-- What is the main capability or idea behind this repository? -->
|
||||
<!-- What problem does it try to solve? -->
|
||||
Turn a pile of source documents into traceable evidence. A user opens a
|
||||
document, highlights a passage, and the app captures a durable, re-resolvable
|
||||
selector plus the surrounding context. Those captures become citations that can
|
||||
be linked, grouped into evidence sets, and exported. During the umbrella-first
|
||||
MVP the app also hosts subsystems that are being extracted into their own repos
|
||||
as they stabilize.
|
||||
|
||||
---
|
||||
|
||||
## In Scope
|
||||
|
||||
<!-- What this repository is responsible for. -->
|
||||
<!-- Be explicit and concrete. -->
|
||||
|
||||
-
|
||||
-
|
||||
-
|
||||
- The application shell, viewer, and session management (upload, sample
|
||||
sessions, export/re-import ZIP)
|
||||
- Anchoring: creating and resolving selectors against document representations
|
||||
- Evidence capture, evidence links, evidence sets, citation cards, and binders
|
||||
- Viewer URL resolution and blob-vs-fixture policy for uploaded PDFs
|
||||
- The source ↔ anchor round-trip integration contract
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope
|
||||
|
||||
<!-- What this repository deliberately does NOT do. -->
|
||||
<!-- This is often more important than "In Scope". -->
|
||||
|
||||
-
|
||||
-
|
||||
-
|
||||
- Headless document ingest / fingerprinting / extraction — owned by
|
||||
`evidence-source` (consumed here via the `@source` façade)
|
||||
- The shared domain model and engine services — owned by `citation-engine`
|
||||
(`@citation-evidence/engine`)
|
||||
- Persisting evidence to a server backend (MVP is browser/session-local)
|
||||
|
||||
---
|
||||
|
||||
## Relevant When
|
||||
|
||||
<!-- When should someone consider using or exploring this repository? -->
|
||||
|
||||
-
|
||||
-
|
||||
-
|
||||
- You are working on the end-user evidence workflow (capture, link, organize)
|
||||
- You are changing the viewer, session lifecycle, or app UI
|
||||
- You need the integration surface that ties ingest, anchoring, and binders together
|
||||
|
||||
---
|
||||
|
||||
## Not Relevant When
|
||||
|
||||
<!-- When should someone ignore this repository? -->
|
||||
|
||||
-
|
||||
-
|
||||
-
|
||||
- You need to change how documents are ingested/extracted (see `evidence-source`)
|
||||
- You need to change the `Document`/selector/evidence contracts (see `citation-engine`)
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
|
||||
<!-- Rough indication of maturity. No strict format required. -->
|
||||
- Status: active
|
||||
- Implementation: substantial (umbrella-first MVP functional; 125-test suite green)
|
||||
- Stability: evolving (subsystems being extracted into standalone repos)
|
||||
- Usage: internal / personal (MVP)
|
||||
|
||||
- Status: <!-- e.g. concept / experimental / active / stable / deprecated -->
|
||||
- Implementation: <!-- e.g. idea / partial / substantial / complete -->
|
||||
- Stability: <!-- e.g. unstable / evolving / stable -->
|
||||
- Usage: <!-- e.g. none / personal / internal / production -->
|
||||
|
||||
<!-- Add any notes that help set expectations. -->
|
||||
The PDF ingest slice was extracted into `evidence-source` (ESRC-WP-0001) and is
|
||||
now consumed across the repo boundary. No umbrella-owned workplans are currently
|
||||
open; active change is driven from the extracted subsystem repos.
|
||||
|
||||
---
|
||||
|
||||
## How It Fits
|
||||
|
||||
<!-- Where does this repository sit in the bigger picture? -->
|
||||
|
||||
- Upstream dependencies:
|
||||
- Downstream consumers:
|
||||
- Often used with:
|
||||
- Upstream dependencies: `citation-engine` (contracts + engine), `evidence-source` (PDF ingest)
|
||||
- Downstream consumers: end users of the evidence workspace
|
||||
- Often used with: `citation-engine`, `evidence-source`
|
||||
|
||||
---
|
||||
|
||||
## Terminology
|
||||
|
||||
<!-- Terms that are important to understand this repo. -->
|
||||
<!-- Especially useful if naming differs from other repos. -->
|
||||
|
||||
- Preferred terms:
|
||||
- Also known as:
|
||||
- Potentially confusing terms:
|
||||
- Preferred terms: citation, selector, evidence set, binder, representation
|
||||
- Also known as: "the umbrella" / "the app"
|
||||
- Potentially confusing terms: "source" (here means the app's `src/source`
|
||||
façade over `evidence-source`, not raw source documents)
|
||||
|
||||
---
|
||||
|
||||
## Related / Overlapping Repositories
|
||||
|
||||
<!-- List repositories that have similar or adjacent responsibilities. -->
|
||||
<!-- Helps detect duplication and navigate the ecosystem. -->
|
||||
|
||||
- <repo-name> — <!-- how it relates -->
|
||||
- `citation-engine` — shared domain model and engine services this app builds on
|
||||
- `evidence-source` — headless PDF ingest extracted from this repo's `src/source`
|
||||
|
||||
---
|
||||
|
||||
## Getting Oriented
|
||||
|
||||
<!-- If someone decides to look deeper, where should they start? -->
|
||||
|
||||
- Start with:
|
||||
- Key files / directories:
|
||||
- Entry points:
|
||||
- Start with: `README.md`, then `wiki/ArchitectureOverview.md`
|
||||
- Key files / directories: `src/app/` (shell + sessions), `src/anchor/`
|
||||
(selectors), `src/binder/`, `src/work/` (session/engine context)
|
||||
- Entry points: the Vite app (`pnpm dev`); `tests/integration/` for end-to-end contracts
|
||||
|
||||
---
|
||||
|
||||
## Provided Capabilities
|
||||
|
||||
<!-- What can this repo's domain provide to other domains on request? -->
|
||||
<!-- Each capability block is parsed by the state-hub capability catalog ingest. -->
|
||||
<!-- Remove the examples and add your own, or leave empty if none. -->
|
||||
|
||||
<!--
|
||||
```capability
|
||||
type: infrastructure
|
||||
title: Example capability title
|
||||
description: What this capability provides, in one or two sentences.
|
||||
keywords: [keyword1, keyword2, keyword3]
|
||||
```
|
||||
-->
|
||||
<!-- The reusable ingest capability now lives in evidence-source's registry.
|
||||
This umbrella currently exposes no standalone capability of its own. -->
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
<!-- Anything else worth knowing. Keep it short. -->
|
||||
Subsystems graduate from `src/` into sibling repos as they stabilize
|
||||
(`citation-engine`, `evidence-source`); the umbrella keeps app/viewer/session
|
||||
concerns and the cross-subsystem integration tests.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue