tegwick
cf57a9bb50
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>
121 lines
3.8 KiB
Markdown
121 lines
3.8 KiB
Markdown
# SCOPE
|
|
|
|
> This file helps you quickly understand what this repository is about,
|
|
> when it is relevant, and when it is not.
|
|
> It is intentionally lightweight and may be incomplete.
|
|
|
|
---
|
|
|
|
## One-liner
|
|
|
|
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
|
|
|
|
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
|
|
|
|
- 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
|
|
|
|
- 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
|
|
|
|
- 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
|
|
|
|
- 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
|
|
|
|
- Status: active
|
|
- Implementation: substantial (umbrella-first MVP functional; 125-test suite green)
|
|
- Stability: evolving (subsystems being extracted into standalone repos)
|
|
- Usage: internal / personal (MVP)
|
|
|
|
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
|
|
|
|
- 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
|
|
|
|
- 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
|
|
|
|
- `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
|
|
|
|
- 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
|
|
|
|
<!-- The reusable ingest capability now lives in evidence-source's registry.
|
|
This umbrella currently exposes no standalone capability of its own. -->
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
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.
|