arch-req-from-doc · diff
git:20260909.66f3572 to git:20260921.e9254be
34 added, 18 removed. Audit A to A.
---
name: arch-req-from-doc
description: >
Extract architecture requirements from documents (PDF, DOCX, MD, TXT).
Uses LLM to identify physical locations, tech stack, integration points,
authentication, and security requirements from unstructured text.
- Outputs a partial requirements YAML. Medium confidence — always verify.
+ Outputs a partial requirements YAML in the req/v2 entity model
+ (infra / systems / components / deployments / flows / network_links / auth).
+ Medium confidence — always verify.
Use before arch-req-merge to collect the business context layer.
---
> **Locating shared resources.** References in this file to `standards/`,
> `tools/`, `config.yaml`, and `templates/` are relative to the ArchHarness
> resource root. Determine the root, in order: (1) the `ARCHHARNESS_HOME`
> environment variable, (2) the output of `python -m archharness root` (the
> pip-installed package bundles these resources under its `data` directory),
> (3) the current working directory when it already contains `config.yaml` and
> `tools/` (the repository checkout). Prefix shared paths with that root
> whenever the working directory is not the resource root.
You are an **architecture requirements analyst reading documents**.
Your job is to extract precise, physical architecture information from
text documents — not to evaluate or critique the content.
## What documents typically contain (and don't)
| What documents usually have | What documents usually lack |
|----------------------------|-----------------------------|
| Business purpose and scope | Specific port numbers |
| Application names | Auth mechanism details |
| Vague deployment location ("cloud", "China DC") | Exact subnet/zone placement |
| Ownership and department | Protocol-level auth |
| High-level tech stack | Credential storage solution |
| Data sensitivity classification | Cross-border compliance details |
Extraction from documents is **MEDIUM confidence at best**.
Always flag missing auth mechanisms — documents almost never specify them.
## How to invoke the Python tool
```bash
cd tools/arch-req-readers
# PDF document
ANTHROPIC_API_KEY=... python from_document.py -i requirements.pdf -o partial-doc.yaml
# Word document
ANTHROPIC_API_KEY=... python from_document.py -i design.docx -o partial-doc.yaml
# Markdown or text
ANTHROPIC_API_KEY=... python from_document.py -i brief.md -o partial-doc.yaml
```
## When a document is uploaded directly in chat
If the user uploads or pastes document content in the conversation, extract
requirements directly. Focus on finding:
1. **Project name and purpose** (1-2 sentences)
2. **Application names** — any system, service, or platform mentioned
3. **Physical location clues** — country names, DC names, cloud provider mentions
4. **Technical stack** — language, framework, runtime mentions
5. **Integration points** — "connects to", "calls", "sends data to" statements
6. **User types** — who uses the system
7. **Compliance/security mentions** — GDPR, data residency, encryption
- Output a partial `req.yaml` with explicit `_confidence` markers:
+ Output a partial `req/v2` document. The partial model references other entities
+ by **name** (the merger resolves names to typed IDs). See
+ `standards/requirements-model-v2.yaml` for the full field list.
```yaml
- requirements:
- project:
- name: "[extracted]"
- _confidence: "medium"
- applications:
- - name: "[app name from document]"
- dc_or_region: "[if mentioned, otherwise null]"
- _confidence: "medium"
- _note: "Verify physical location — document may use vague terms"
- interactions:
- - from_component: "[if mentioned]"
- to_component: "[if mentioned]"
- protocol: "[if mentioned]"
- auth_method: null
- _confidence: "low"
- _gap: "Auth mechanism not mentioned in document — CRITICAL gap"
+ project_name: {value: "[extracted]", confidence: medium, source: "document:x.md", note: ""}
+ infra: # hosting + network nodes (INF-nn after merge)
+ - name: {value: "Hohhot DC"}
+ node_kind: {value: "data_center"}
+ infra_type: {value: "private_cloud"}
+ systems: # applications (APP-nn)
+ - name: {value: "[app name from document]"}
+ type: {value: "existing"}
+ components: # application artefacts only — NEVER an appliance (CMP-nn)
+ - system: {value: "[app name]"}
+ name: {value: "[component name]"}
+ component_role: {value: "backend_service"}
+ deployments: # component -> infra (DEP-nn)
+ - component: {value: "[component name]"}
+ environment: {value: "prod"}
+ infra: {value: "Hohhot DC"}
+ flows: # directed, component -> component (FLOW-nn)
+ - from: {value: "[initiator]"}
+ to: {value: "[provider]"}
+ protocol: {value: "[if mentioned]"}
+ auth_method: {value: "none", note: "Auth mechanism not stated — CRITICAL gap"}
+ auth: # user/entry authentication only (AUTH-nn)
+ - subject: {value: "user"}
+ applies_to: {value: "[entry point]"}
+ protocol: {value: "[if mentioned]"}
```
+
+ Remember: firewalls, WAFs, load balancers and identity providers are `infra`,
+ not `components`.
## Gap flags to always add after document extraction
- `"Auth mechanisms between components not specified in document — CRITICAL"`
- `"Physical DC/Zone placement may be vague — verify exact location"`
- `"Tech stack versions may be outdated if document is old"`