Skip to content

docs: two-voice (civic staff + IT) overhaul with architecture diagrams #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
scottconverse merged 1 commit into from
Jun 29, 2026
Merged

docs: two-voice (civic staff + IT) overhaul with architecture diagrams #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 96 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,62 +2,118 @@

CivicAccess is the CivicSuite module for accessibility, plain-language, multilingual, and ADA Title II review-support workflows.

Current state: **v0.4.0 standalone readiness candidate**. This repo contains a FastAPI package aligned to the published CivicCore v1.2.0 release wheel, health/root endpoints, readiness gates, WCAG-aligned review support, database-backed review records that default to the shared CivicCore PostgreSQL, accessible form planning, accessible publishing workflow checks, plain-language rewrites, multilingual draft variants, ADA Title II review-support packages, tagged-PDF expectations, records-ready export checklists, a stateless public accessibility checker at `/civicaccess`, and a staff review/export workspace at `/civicaccess/staff`. As of v0.4.0, persistent writes (saving reviews and records exports) require a trusted-write token, every write/export emits a persisted audit event, and the public surface analyzes without persisting. The previous `v1.0.0` release was published in error and remains historical evidence only.
> **v0.4.0 · early release.** CivicAccess does **not** give legal advice, certify ADA compliance, issue official translations, or publish anything on its own — your staff, ADA coordinator, translators, and legal counsel always make the final call.

CivicAccess does **not** provide legal advice, certified ADA compliance, official translation certification, live LLM calls, or final publication approval. City staff, ADA coordinators, translators, and qualified reviewers remain responsible for publication decisions.
This README has two audiences:

## What CivicAccess Does
- **Civic staff (clerks, communicators, ADA coordinators)** — see the [User Manual, Part 1](USER-MANUAL.md#part-1--for-civic-staff) or the [landing page](docs/index.html). Short version below.
- **IT & technical staff** — architecture, API, persistence, and security are below.

- Reviews public content for actionable WCAG-aligned issues.
- Reports local review-record persistence readiness through `/ready`.
- Provides a staff queue for saved accessibility reviews and records-ready exports.
- Checks accessible form publication basics: labels, required fields, validation copy, and record context.
- Builds a staff publication workflow with accessibility, plain-language, translation-review, export, and approval steps.
- Rewrites common municipal jargon into plainer language while preserving source/rewrite provenance.
- Produces multilingual draft variants that are explicitly marked for human review.
- Produces ADA Title II review-support checklists without claiming certification.
- Checks tagged-PDF heading expectations before publication.
- Builds records-ready export checklists that preserve source/rewrite provenance.
- Provides a local API-backed accessibility review UI at `/civicaccess`.
---

## Release Integrity Correction
## For civic staff (the short version)

CivicAccess was previously demoted after a false `v1.0.0` release. The current branch is rebuilding that truthfully: it now has automatic local persistence, a staff workspace, and integration contracts, but it still must pass the current module-completion audit, suite integration proof, and clean-machine evidence before any finished/public-use label can be promoted. See [docs/release-integrity-correction-2026-05-21.md](docs/release-integrity-correction-2026-05-21.md).
CivicAccess helps your office put out public notices everyone can read — and keep a record proving you checked.

## Developer Quickstart
- Paste a draft into the **public checker** to get instant, plain-language fixes. Nothing is saved — it's a safe place to try things.
- To keep a review **on the record**, save it in the **staff workspace** and export a copy you can hand to a public-records request.
- It also rewrites jargon, drafts translations for a human reviewer, and walks ADA Title II reviews — but never publishes anything on its own.

Full walkthrough: [User Manual, Part 1](USER-MANUAL.md#part-1--for-civic-staff).

---

## For IT & technical staff

CivicAccess is a deterministic FastAPI module (Python), pinned to the published CivicCore v1.2.0 release wheel — no model/LLM calls and no outbound network calls, so output is reproducible.

### Architecture

In CivicSuite Windows Local, a Tauri supervisor runs CivicAccess (and peer modules) against a bundled PostgreSQL on `127.0.0.1:15432`; CivicAccess uses a dedicated `civicaccess` schema. The supervisor's backup captures the whole data directory, so module data rides along.

```mermaid
flowchart TB
Resident["Resident (browser)"] -->|"public, read-only"| Pub["/civicaccess"]
Staff["City staff (browser)"] -->|"WebView2 UI"| StaffUI["/civicaccess/staff"]

subgraph Sup["Tauri supervisor — local machine only"]
CA["CivicAccess (FastAPI)"]
Peers["Peer modules: CivicClerk, CivicCode, CivicNotice, …"]
PG[("Bundled PostgreSQL :15432")]
end

Pub --> CA
StaffUI --> CA
CA -->|"DATABASE_URL → civicaccess schema"| PG
Peers --> PG
CA -->|"depends on"| Core["CivicCore v1.2.0"]
CA -. records-export .-> Records["CivicRecords AI"]
Sup -. "wholesale backup of Data/" .-> Backup[("Backup folder")]
```

### What it provides

- A **stateless public accessibility checker** (`/civicaccess`) that flags WCAG-aligned issues with actionable, standard-referenced fixes — no persistence, no token.
- A **token-guarded staff workspace** (`/civicaccess/staff`) for saving reviews and building records-ready exports.
- Plain-language rewrites that preserve source/rewrite provenance.
- Multilingual draft variants explicitly marked for human review.
- ADA Title II review-support checklists (without claiming certification).
- Accessible-form and tagged-PDF expectation checks, and a staff publication workflow.
- A persisted **audit trail** of every write/export, and integration contracts for downstream publishers.

### Runtime API

| Method & path | Auth | Persists? | Purpose |
|---|---|---|---|
| `GET /` · `GET /health` | — | no | Status, boundaries, versions |
| `GET /ready` · `GET /api/v1/civicaccess/readiness` | — | no | Persistence readiness gate |
| `GET /civicaccess` · `GET /civicaccess/staff` | — | no | Public checker / staff workspace (UI) |
| `POST /api/v1/civicaccess/analyze` | — | no | Stateless accessibility analysis |
| `POST /api/v1/civicaccess/review` | **token** | **yes** | Save a review record (+ audit) |
| `GET /api/v1/civicaccess/reviews` · `GET …/reviews/{id}` | — | no | List / retrieve saved reviews |
| `POST /api/v1/civicaccess/reviews/{id}/records-export` | **token** | **yes** (audit) | Records-ready export (+ audit) |
| `GET /api/v1/civicaccess/integration-contracts` | — | no | Published integration contracts |
| `POST /api/v1/civicaccess/plain-language` · `…/language-variant` | — | no | Plain-language rewrite / multilingual draft |
| `POST /api/v1/civicaccess/forms` · `…/publishing-workflow` | — | no | Accessible-form checks / publication workflow |
| `POST /api/v1/civicaccess/ada-title-ii` · `…/tagged-pdf` · `…/export` | — | no | ADA Title II checklist / tagged-PDF / export checklist |

Token-guarded writes require `X-CivicAccess-Write-Token` matching `CIVICACCESS_TRUSTED_WRITE_TOKEN` (constant-time compare): missing/invalid → `403`, guard not configured → `503`. The token is never embedded in served HTML — the staff page provides a field where an operator pastes it.

### Persistence & configuration

| Variable | Purpose |
|---|---|
| `DATABASE_URL` | Shared CivicCore PostgreSQL (supervisor-injected) — the production default |
| `CIVICACCESS_REVIEW_DB_URL` | Explicit SQLAlchemy URL override |
| `CIVICACCESS_DATA_DIR` | Directory for the SQLite dev fallback (`data/civicaccess-reviews.db`) |
| `CIVICACCESS_TRUSTED_WRITE_TOKEN` | **Required** server secret for persistent writes |

Resolution order: `CIVICACCESS_REVIEW_DB_URL` → `DATABASE_URL` (converted to a sync psycopg2 URL) → SQLite dev fallback. Use the `civicaccess-db-status` console script with an explicit URL to preflight a database.

### Security

Persistence-write routes require the trusted-write token (constant-time compare, fails closed); read and stateless-analysis routes are open. Every write/export persists an `audit_events` row; `review.create`'s audit is committed atomically with the record. No model/LLM or outbound network calls. Review + audit data live in the shared Postgres cluster and are captured by the supervisor's wholesale `Data/` backup. See [SECURITY.md](SECURITY.md).

### Developer quickstart

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install https://github.com/CivicSuite/civiccore/releases/download/v1.2.0/civiccore-1.2.0-py3-none-any.whl
python -m pip install -e ".[dev]"
python -m pytest -q
# Full release gate (requires a real PostgreSQL):
$env:CIVICACCESS_POSTGRES_TEST_URL = "postgresql+psycopg2://USER:PW@HOST:PORT/DB"
bash scripts/verify-release.sh
```

## Runtime API

- `GET /` returns current module status and boundaries.
- `GET /health` returns package and CivicCore version information.
- `GET /ready` and `GET /api/v1/civicaccess/readiness` report whether local review persistence is configured and schema-ready.
- `GET /civicaccess` returns the API-backed public accessibility review UI.
- `GET /civicaccess/staff` returns the staff review queue and records-export workspace.
- `POST /api/v1/civicaccess/review` returns accessibility findings and next steps.
- `GET /api/v1/civicaccess/reviews` lists saved review records.
- `GET /api/v1/civicaccess/reviews/{review_id}` retrieves persisted review records.
- `POST /api/v1/civicaccess/reviews/{review_id}/records-export` builds a CivicRecords-ready retention export.
- `GET /api/v1/civicaccess/integration-contracts` publishes upstream/downstream integration contracts.
- `POST /api/v1/civicaccess/forms` returns accessible form publication checks.
- `POST /api/v1/civicaccess/publishing-workflow` returns staff publication workflow blockers and steps.
- `POST /api/v1/civicaccess/plain-language` returns a deterministic plain-language rewrite.
- `POST /api/v1/civicaccess/language-variant` returns a multilingual draft variant requiring human review.
- `POST /api/v1/civicaccess/ada-title-ii` returns ADA Title II review-support checklist items.
- `POST /api/v1/civicaccess/tagged-pdf` returns tagged-PDF heading expectations.
- `POST /api/v1/civicaccess/export` returns a records-ready accessibility export checklist.

By default, CivicAccess stores review records in `data/civicaccess-reviews.db` under the process working directory. Set `CIVICACCESS_DATA_DIR` to choose a different local data directory, or set `CIVICACCESS_REVIEW_DB_URL` to use an explicit SQLAlchemy database URL. `/ready` is expected to be ready when the local schema can be created and verified.

Use the `civicaccess-db-status` console script with an explicit SQLAlchemy URL when an operator wants to preflight a non-default review database.
### Integration

CivicAccess **depends on CivicCore** (CivicCore does not depend on CivicAccess). It publishes contracts at `/api/v1/civicaccess/integration-contracts`, hands records exports to **CivicRecords AI**, and supports downstream publishers (zone, plan, permit, inspect, grants, procure).

### Release status

`v0.4.0` is an early release; probe gaps #1–#4 (clean install, staff/public authz, audit logging, backup/restore durability) are closed with evidence — see [PROBE-PROGRESS.md](PROBE-PROGRESS.md). City-core membership (desktop registry record, 6-module profile) and a clean-VM accessibility acceptance pass are later phases. The earlier `v1.0.0` release was published in error and is retained only as historical evidence; see [docs/release-integrity-correction-2026-05-21.md](docs/release-integrity-correction-2026-05-21.md).

## License

Expand Down
94 changes: 87 additions & 7 deletions README.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,94 @@
CivicAccess
===========

CivicAccess is the CivicSuite module for accessibility, plain-language, multilingual, and ADA Title II review-support workflows.
CivicAccess is the CivicSuite module for accessibility, plain-language,
multilingual, and ADA Title II review-support workflows.

Current state: v0.4.0 standalone readiness candidate. This repo contains a deterministic FastAPI package aligned to the published CivicCore v1.2.0 release wheel, health/root endpoints, readiness gates, WCAG-aligned review support, database-backed review records that default to the shared CivicCore PostgreSQL (with a SQLite dev fallback), accessible form planning, accessible publishing workflow checks, plain-language rewrites, multilingual draft variants, ADA Title II review-support packages, tagged-PDF expectations, records-ready export checklists, a stateless public accessibility checker at /civicaccess, and a trusted-write-token-guarded staff persistence/export surface with persisted audit events. The previous v1.0.0 release was published in error and is superseded by this honest sub-1.0.0 label.
Status: v0.4.0 - early release. CivicAccess does NOT give legal advice, certify ADA
compliance, issue official translations, or publish anything on its own - your staff,
ADA coordinator, translators, and legal counsel always make the final call.

CivicAccess does not provide legal advice, certified ADA compliance, official translation certification, live LLM calls, or final publication approval. City staff, ADA coordinators, translators, and qualified reviewers remain responsible for publication decisions.
This README serves two audiences. Civic staff: see the short version below and
USER-MANUAL.md (Part 1). IT/technical: see the technical section below.
(For rendered architecture diagrams, read README.md / USER-MANUAL.md.)

Run:

python -m pip install -e ".[dev]"
python -m pytest -q
bash scripts/verify-release.sh
FOR CIVIC STAFF (the short version)
-----------------------------------

CivicAccess helps your office put out public notices everyone can read - and keep
a record proving you checked.
- Paste a draft into the public checker to get instant, plain-language fixes.
Nothing is saved - it's a safe place to try things.
- To keep a review on the record, save it in the staff workspace and export a copy
you can hand to a public-records request.
- It also rewrites jargon, drafts translations for a human reviewer, and walks ADA
Title II reviews - but never publishes anything on its own.
Full walkthrough: USER-MANUAL.md (Part 1).


FOR IT & TECHNICAL STAFF
------------------------

CivicAccess is a deterministic FastAPI module (Python), pinned to the published
CivicCore v1.2.0 release wheel - no model/LLM calls and no outbound network calls.

Architecture (text sketch; see README.md for the rendered diagram):

Resident --> /civicaccess (public, no token) --+
+--> CivicAccess (FastAPI) --> PostgreSQL :15432
City staff --> /civicaccess/staff (write token) --+ | (civicaccess schema)
+-- depends on ----> CivicCore v1.2.0
+-- records-export -> CivicRecords AI

All of the above runs inside the Tauri supervisor on the local machine. The
supervisor injects DATABASE_URL and backs up the whole Data/ directory (which
includes the PostgreSQL cluster), so CivicAccess data is captured with it.

What it provides:
- A stateless public accessibility checker (/civicaccess): WCAG-aligned issues with
actionable, standard-referenced fixes. No persistence, no token.
- A token-guarded staff workspace (/civicaccess/staff): save reviews, build
records-ready exports.
- Plain-language rewrites (source/rewrite provenance preserved).
- Multilingual draft variants, explicitly marked for human review.
- ADA Title II review-support checklists (without claiming certification).
- Accessible-form and tagged-PDF expectation checks; a staff publication workflow.
- A persisted audit trail of every write/export; integration contracts.

Persistence & configuration:
- DATABASE_URL ................. shared CivicCore PostgreSQL (supervisor-injected); the default
- CIVICACCESS_REVIEW_DB_URL .... explicit SQLAlchemy URL override
- CIVICACCESS_DATA_DIR ......... directory for the SQLite dev fallback
- CIVICACCESS_TRUSTED_WRITE_TOKEN .. REQUIRED server secret for persistent writes
Resolution order: CIVICACCESS_REVIEW_DB_URL -> DATABASE_URL (converted to sync
psycopg2) -> SQLite dev fallback. Preflight with the civicaccess-db-status script.

Security:
- Persistence-write routes (/review, /reviews/{id}/records-export) require the
X-CivicAccess-Write-Token header (constant-time compare): missing/invalid -> 403,
guard not configured -> 503 (fails closed). Read and analyze routes are open.
- The server token is never embedded in served HTML; the staff page provides a
field where an operator pastes it.
- Every write/export persists an audit_events row; review.create is atomic with the
record. No model/LLM or outbound network calls.

Developer quickstart:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install https://github.com/CivicSuite/civiccore/releases/download/v1.2.0/civiccore-1.2.0-py3-none-any.whl
python -m pip install -e ".[dev]"
python -m pytest -q
# Full release gate (requires a real PostgreSQL):
$env:CIVICACCESS_POSTGRES_TEST_URL = "postgresql+psycopg2://USER:PW@HOST:PORT/DB"
bash scripts/verify-release.sh

Release status:
v0.4.0 is an early release; probe gaps #1-#4 (clean install, staff/public authz,
audit logging, backup/restore durability) are closed with evidence (PROBE-PROGRESS.md).
City-core membership and a clean-VM accessibility acceptance pass are later phases.
The earlier v1.0.0 release was published in error and is retained only as historical
evidence.


License: Code is Apache 2.0. Documentation is CC BY 4.0.
Loading