Skip to content

Commit 58db27f

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
docs: document consent pipeline
Describes the consent pipeline: intsoc-transactor (check/fix/submit) -> consent-aware-http (consent middleware, planned) -> branch-newspaper (publication platform). Documents what each component does and how they connect. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent fbf27ad commit 58db27f

1 file changed

Lines changed: 113 additions & 0 deletions

File tree

‎docs/PIPELINE.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
4+
# Consent Pipeline
5+
6+
## Overview
7+
8+
The consent pipeline connects three components that together enable
9+
consent-aware document processing and publication for Internet Society
10+
standards work:
11+
12+
```
13+
intsoc-transactor --> consent-aware-http --> branch-newspaper
14+
(check/fix/submit) (consent middleware) (publication platform)
15+
```
16+
17+
## Components
18+
19+
### intsoc-transactor (this repo)
20+
21+
**Purpose:** Check, fix, and submit documents across all Internet Society
22+
streams (IETF, IRTF, IAB, Independent Stream, IANA, RFC Editor).
23+
24+
**What it does:**
25+
- Parses RFC XML v3 and plain-text Internet-Drafts
26+
- Validates documents against per-stream requirements (idnits, metadata, SPDX)
27+
- Classifies fixes as AutoSafe, Recommended, or ManualOnly
28+
- Tracks document lifecycle with per-stream state machines (20+ states for IETF)
29+
- Provides CLI (`intsoc check/fix/submit/status/init`) and Tauri desktop GUI
30+
31+
**Key crates:**
32+
- `intsoc-core` — domain model, state machines, validation framework
33+
- `intsoc-parser` — RFC XML v3 and plain-text parsing
34+
- `intsoc-fixer` — fix engine with safety classification
35+
- `intsoc-nickel` — Nickel template rendering and policy validation
36+
- `intsoc-api` — IETF Datatracker and IANA API clients
37+
- `intsoc-cli` — CLI binary
38+
39+
### consent-aware-http (planned)
40+
41+
**Purpose:** HTTP middleware layer that enforces consent semantics on document
42+
submissions and API interactions.
43+
44+
**Status:** Not yet created as a standalone repository.
45+
46+
**Planned responsibilities:**
47+
- Enforce HTTP 430 Consent Required responses where consent has not been given
48+
- Track consent state across document submission workflows
49+
- Bridge between intsoc-transactor's submission engine and downstream publication
50+
- Provide consent audit trails for governance compliance
51+
52+
**Design intent:** When intsoc-transactor submits a document or interacts with
53+
external APIs (IETF Datatracker, IANA registries), consent-aware-http ensures
54+
that all required consents (author consent, IPR declarations, publication
55+
consent) have been obtained before the request proceeds.
56+
57+
### branch-newspaper
58+
59+
**Purpose:** Phoenix LiveView application for citizen journalists and union
60+
branches, with decentralised content storage.
61+
62+
**What it does:**
63+
- Meeting minutes management (create, edit, organise)
64+
- IPFS integration for decentralised, immutable content storage
65+
- Real-time UI via Phoenix LiveView
66+
- Tag-based organisation for content discovery
67+
68+
**Tech stack:** Elixir, Phoenix 1.8.1, LiveView 1.1.0, SQLite3/PostgreSQL, IPFS
69+
70+
**Connection to the pipeline:** branch-newspaper is the publication endpoint
71+
where processed and consent-verified documents are made available to union
72+
branches and citizen journalists. Content that passes through intsoc-transactor
73+
(validated, fixed) and consent-aware-http (consent-verified) can be published
74+
through branch-newspaper's IPFS-backed storage.
75+
76+
## How They Connect
77+
78+
```
79+
1. Author creates/edits an Internet-Draft
80+
|
81+
v
82+
2. intsoc-transactor: check + fix
83+
- Validates RFC XML structure
84+
- Checks SPDX headers, metadata, idnits
85+
- Applies AutoSafe fixes
86+
- Tracks state machine transitions
87+
|
88+
v
89+
3. consent-aware-http: consent gate (planned)
90+
- Verifies author consent, IPR declarations
91+
- Enforces HTTP 430 where consent missing
92+
- Maintains consent audit trail
93+
|
94+
v
95+
4. branch-newspaper: publish
96+
- Stores validated content on IPFS
97+
- Makes documents available via LiveView UI
98+
- Tags and organises for discovery
99+
```
100+
101+
## Current Status
102+
103+
| Component | Status | Repository |
104+
|-----------|--------|-----------|
105+
| intsoc-transactor | Active development | This repo |
106+
| consent-aware-http | Planned | Not yet created |
107+
| branch-newspaper | Active development | [branch-newspaper](https://github.com/hyperpolymath/branch-newspaper) |
108+
109+
## See Also
110+
111+
- [intsoc-transactor README](../README.adoc) — full project documentation
112+
- [branch-newspaper](https://github.com/hyperpolymath/branch-newspaper) — publication platform
113+
- [HTTP 430 Consent Required](https://datatracker.ietf.org/doc/draft-jewell-http-430-consent-required/) — the consent HTTP status code

0 commit comments

Comments
 (0)