Repository navigation
docs: PromiseTracker v3 specification - #637
Open
kelvinkipruto wants to merge 6 commits into
Open
kelvinkipruto wants to merge 6 commits into
kelvinkipruto wants to merge 6 commits into
Conversation
Twelve documents under docs/v3/ describing a re-architecture of
PromiseTracker that removes the hard dependencies on Airtable and Meedan
Check. Both are load-bearing in v2: Airtable holds countries, politicians
and documents and doubles as the work queue, and nothing creates a promise
record except the Check sync.
Structure:
REVIEW.md review brief: five decisions to argue about, six
questions with owners
README.md index, why v3, the eighteen decisions
01-product.md problem, users, jobs to be done, core flows, scope
02-architecture.md kernel, plugin-core, five ports and their adapters
03-data-model.md every collection and global, field by field
04-governance.md recordStatus, the computed _status, the cascade, roles
05-pipeline.md ingest, extract, AI, review, publish
06-plugins.md superdesk, native review, ai, tika, airtable
07-public-site.md routing, caching, search, SEO, embeds, public API
08-security-ops.md auth, secrets, SSRF, observability, deployment
09-launch.md seeding order, retiring the integrations, launch
10-roadmap.md phasing, scale targets, open questions
Load-bearing decisions:
- The core is itself a plugin, so it publishes the same extension API every
integration uses. With PT_PLUGINS=core alone the system is a complete,
publishable tracker on MongoDB and S3 with no credentials, which is also
what CI runs against.
- No multi-tenancy. Country is a path segment with typed actor segments,
as in /ke/politicians/william-ruto, replacing v2's tenant subdomains and
its userHasAccessToAllTenants: () => true.
- One actors collection with a kind of person, party, institution or place,
replacing political-entities and its free-text region and position. A
person carries an offices[] history.
- Claim updates are a first-class collection, and a claim's currentStatus
derives from the latest published update rather than being typed in. v2
renders its timeline from events={[]}.
- Ingest splits into source connectors, content extractors and structured
importers, so a partner's CSV becomes records without AI while a
manifesto PDF goes through extraction, AI and review.
- Publication is one writable field, recordStatus, plus a computed _status
that accounts for ancestry, replacing v2's three inconsistent conventions.
The product has never gone live, so section 9 is a launch plan rather than
a migration: no field mapping, no cutover, no redirect map.
Section 6.2 records the Superdesk API constraints found during research,
including the deployment-specific Content API prefix, the date-only
start_date with a seven-day default window, the absence of ETags, and the
subscriber-scoped visibility that returns 200 with an empty list when no
product matches. Ten instance details are marked CONFIRM and listed in
section 10.3 as blocking for phase 3.
Also noted for fixing rather than porting: cleanText in
src/tasks/extractDocuments.ts:19 strips every non-ASCII character, which
corrupts accented text on a bilingual en/fr product.
Specification only. No code changes.
Two documents under docs/spec/, both derived from the working set in docs/v3/. promisetracker-v3-product-spec.md is the high-level document for the team. It follows one promise through the platform in eight steps, from setting up a country to hearing from citizens, and avoids technical terms, data types and file references. It names the three places verification can happen: the built-in review queue, Superdesk, and Meedan Check. promisetracker-v3-system-specification.md is the full technical spec as one file, structured like the v2.0 reference architecture: executive summary, system and plugin architecture, data models, pipeline, error handling, frontend, testing, security, operations, performance, workflow, API and design decisions, with the items still to confirm collected in an appendix. PDF renditions are generated from these files and are not committed.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…lugin Rewrites the full system specification so a reader who is not a developer can follow it, while keeping the technical detail. - Each section opens with a short plain-language summary. - A key terms table defines actor, claim, verdict, plugin, port, adapter and the other terms before they are used. - Record types are described as field tables instead of TypeScript interfaces, and port contracts as method tables. - v2 file references move to an appendix, so the body reads without them. - Code blocks stay under 75 characters wide and the document uses only headings, tables, lists and fenced code, so it imports into Google Docs without reformatting. Adds plugin-check as a full verification plugin alongside the built-in review queue and plugin-superdesk: the Check GraphQL API and its headers, how a claim maps to a Check item, the createProjectMedia mutation, the report webhook and reconciliation poll, the status-to-verdict mapping, and failure behaviour. Phase 3 now delivers both newsroom plugins.
The PDF renditions are tracked alongside their Markdown sources. This brings both in line with the current text: the product spec now names Meedan Check as a verification option, and the system spec is the rewritten version with the Check plugin.
Rewrites the system and product specifications to match the decisions agreed since the first draft, now recorded as D1 to D36 in section 20 of the system specification. - PostgreSQL replaces MongoDB, on Payload 4 with all its new features: hierarchy for nested areas, crash-safe jobs, authorship, dashboard widgets and per-language publishing. - The public site becomes a replaceable UI layer, built from the redesign, that reads data only through a typed SDK and contract. - Claims of every type stay. Editors define ratings in rating scales, with six ratings in three tiers as the default. - Countries get lists of offices and areas. Actors are people, parties and institutions, with terms of office. Places become areas. - Web addresses put the language first, use /e/ for actors and /p/ for claims, and redirect seat addresses to the current holder. - Version 1 matches what v2 does today, with verification in the built-in queue or Meedan Check. Superdesk comes later. - Shipped as one Docker image under the MIT licence. Adds the MIT licence. Removes docs/v3, which the two documents in docs/spec supersede, and ignores working files: PDFs at the repository root and the revision proposal the specs were rewritten from.
Removes three files committed to the repository root by mistake in dd97fb0: the v2.0 reference specification PDF and an early combined copy of the v3 spec in Markdown and PDF. The current specifications live in docs/spec. The files stay on disk and are now ignored.
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this adds
Specification documents for PromiseTracker v3, plus the MIT licence. No code changes.
docs/spec/promisetracker-v3-product-spec.mddocs/spec/promisetracker-v3-system-specification.mdPDF copies of both sit next to the Markdown files. Start with the product spec.
What v3 changes
Notes for reviewers
docs/v3/, the first draft, is removed in the latest commit and superseded bydocs/spec/.