251 lines
10 KiB
Markdown
251 lines
10 KiB
Markdown
# Addon Skeleton Specification
|
|
|
|
**Project:** kane-diagnostics
|
|
**Version:** 1.0
|
|
**Prerequisite reading:** README.md, DSC-development-map.md, HANDOFF.md, CODING-GUIDELINES.md
|
|
|
|
---
|
|
|
|
## Purpose
|
|
|
|
This document specifies the three addon skeletons to be created as the baseline for the kane-diagnostics project. It is a handoff document — the incoming Assistant reads this, reads the repos, and then works with the operator to build each skeleton before any functional code is written.
|
|
|
|
A skeleton is not a working addon. It is the correct structure, the correct conventions, the correct file layout, and the correct configuration — with placeholder content where the logic will go. A skeleton that compiles and loads without errors is a skeleton that is ready to develop.
|
|
|
|
**Nothing in this document should be built without the operator's input and confirmation at each step.**
|
|
|
|
---
|
|
|
|
## The Three Addons
|
|
|
|
### vs01 — Vital Signs
|
|
|
|
**Purpose:** Present the ten structural preconditions of an HOA association. Public-facing — readable without authentication. This is the first thing a participant reads and the first thing an attorney reads.
|
|
|
|
**Route:** `/vs01`
|
|
|
|
**Access:** Public read. No authentication required to view. HOA_MEMBER standing required to submit a Vital Signs record for a specific association.
|
|
|
|
**What it does:**
|
|
- Presents each of the ten Vital Signs in plain language
|
|
- Explains why each one matters to the homeowner
|
|
- Provides public record lookup guidance for each Vital Sign (Recorder of Deeds, Secretary of State, IDFPR, etc.)
|
|
- Allows a verified participant to submit a Vital Signs record for their association
|
|
- Stores the record via the orchestrator spool
|
|
|
|
**What it does not do:**
|
|
- It does not present scenarios
|
|
- It does not present case law
|
|
- It does not manage attorney listings
|
|
|
|
---
|
|
|
|
### dsc01 — Diagnostic Surface Categories
|
|
|
|
**Purpose:** Present the Diagnostic Surface Categories — the legal surfaces where HOA governance disputes manifest — organized from the homeowner's perspective. Browsable publicly. Case law entries require HOA_MEMBER standing to submit.
|
|
|
|
**Route:** `/dsc01`
|
|
|
|
**Access:** Public read. HOA_MEMBER standing required to submit a diagnostic record or case law entry.
|
|
|
|
**What it does:**
|
|
- Presents the ten Active DSC categories with their diagnostic questions
|
|
- Presents the Vital Sign dependencies for each category
|
|
- Presents case law entries organized by DSC category
|
|
- Connects each DSC category to the relevant Vital Signs
|
|
- Allows verified participants to submit accounts under a specific DSC category
|
|
- Stores records via the orchestrator spool
|
|
|
|
**What it does not do:**
|
|
- It does not present scenarios
|
|
- It does not manage the Vital Signs record
|
|
- It does not manage attorney listings
|
|
|
|
---
|
|
|
|
### scn01 — Scenarios
|
|
|
|
**Purpose:** The participant intake surface. A verified participant reads diagnostic scenarios, writes their account in their own words, and submits. The account is the record.
|
|
|
|
**Route:** `/scn01`
|
|
|
|
**Access:** HOA_MEMBER standing required. Public visitors see the access wall with SASE instructions.
|
|
|
|
**What it does:**
|
|
- Presents the scenario carousel — browse only, no selection required
|
|
- Accepts the participant's account in their own words
|
|
- Writes the submission to the orchestrator spool as a TMP record
|
|
- Provides an operator-only `/scn01/manage` interface for scenario management and TMP review
|
|
|
|
**What it does not do:**
|
|
- It does not present Vital Signs
|
|
- It does not present case law
|
|
- It does not manage attorney listings
|
|
|
|
**Relationship to pilot:**
|
|
The pilot `ds01` addon in `caselaw-document-access` is the functional prototype for this addon. The new `scn01` is a clean rebuild on the complete foundation — not a port of the pilot code. The pilot is reference, not source.
|
|
|
|
---
|
|
|
|
## Skeleton File Structure
|
|
|
|
Each addon skeleton follows this structure. Files marked `[placeholder]` contain the correct structure but no functional logic.
|
|
|
|
```
|
|
hubzilla/addon/{addon}/
|
|
{addon}.php — main addon file: hooks, load/unload, content routing
|
|
{addon}.apd — app descriptor
|
|
mod_{addon}.pdl — PDL layout: aside, content, right_aside
|
|
config.json.template — all config fields documented, no secrets
|
|
Widget/
|
|
{Addon}.php — sidebar widget: navigation, resources, status
|
|
view/
|
|
css/
|
|
{addon}.css — all presentation styles, no inline styles anywhere
|
|
js/
|
|
{addon}.js — all behavior, no inline scripts anywhere
|
|
contracts/
|
|
spool-v1.json — the spool envelope contract this addon produces
|
|
README.md — one paragraph: what this addon does and does not do
|
|
```
|
|
|
|
---
|
|
|
|
## Skeleton Content Requirements
|
|
|
|
### {addon}.php
|
|
|
|
Must contain, in order:
|
|
|
|
1. **File header** — addon name, description, version, min/max Hubzilla version
|
|
2. **Hook registration** — `{addon}_load()` and `{addon}_unload()` with PDL and Widget hooks
|
|
3. **PDL loader** — `{addon}_load_pdl()` following the established convention
|
|
4. **Helper** — `{addon}_h()` — the HTML escape function
|
|
5. **Access state** — `{addon}_access_state()` — returns `'public'`, `'participant'`, or `'operator'`
|
|
6. **Access wall** — `{addon}_access_wall()` — plain language, SASE link
|
|
7. **Content router** — `{addon}_content()` — loads CSS/JS, checks access, routes by path and method
|
|
8. **Config loader** — `{addon}_load_config()`
|
|
9. **CSRF token and verify** — standard pattern
|
|
10. **Placeholder content functions** — one per route, each returning a `// TODO` string with a plain description of what goes here
|
|
|
|
No functional logic in the skeleton. No database calls. No file I/O. No orchestrator calls. Those come after the skeleton is confirmed.
|
|
|
|
### {addon}.apd
|
|
|
|
```
|
|
version: 2
|
|
url: $baseurl/{addon}
|
|
requires: local_channel
|
|
name: {Descriptive name}
|
|
photo: icon:{bootstrap-icon-name}
|
|
categories: Civic Diagnostics
|
|
desc: {One sentence — what this addon does.}
|
|
```
|
|
|
|
### mod_{addon}.pdl
|
|
|
|
```
|
|
[template]default[/template]
|
|
|
|
[region=aside]
|
|
[widget={addon}][/widget]
|
|
[/region]
|
|
|
|
[region=content]
|
|
$content
|
|
[/region]
|
|
|
|
[region=right_aside]
|
|
[widget=notifications][/widget]
|
|
[widget=newmember][/widget]
|
|
[/region]
|
|
```
|
|
|
|
### config.json.template
|
|
|
|
Every field the addon reads from `config.json` must appear here with a descriptive comment and a placeholder value. No field should ever be read from `config.json` that does not first appear in `config.json.template`.
|
|
|
|
```json
|
|
{
|
|
"_note": "Copy to config.json. Do not commit config.json — it contains secrets.",
|
|
"receiver_url": "REPLACE — orchestrator receiver endpoint",
|
|
"node_token": "REPLACE — shared secret for node-to-orchestrator auth",
|
|
"corpus_builder_group_id": 0
|
|
}
|
|
```
|
|
|
|
### Widget/{Addon}.php
|
|
|
|
Must contain:
|
|
- Correct namespace: `namespace Zotlabs\Widget;`
|
|
- Class name matching filename exactly: `class {Addon}`
|
|
- `widget($arr)` method returning sidebar HTML
|
|
- `current_step()` or `current_route()` for navigation state
|
|
- Sidebar navigation showing current location
|
|
- Resources panel using `data-{addon}-resource` attributes — no navigation links
|
|
|
|
### contracts/spool-v1.json
|
|
|
|
The JSON contract this addon produces and POSTs to the orchestrator. Must contain:
|
|
- `_header` block with all required fields documented
|
|
- `_payload` block with the addon-specific fields
|
|
- `_meta` block describing the contract version and purpose
|
|
|
|
This file is the contract. When the payload structure changes, the version increments and a new file is created (`spool-v2.json`). The old contract is never deleted — it documents what the orchestrator must remain able to consume.
|
|
|
|
### {addon}.css
|
|
|
|
Skeleton contains:
|
|
- File header comment with addon name and version
|
|
- Section comments for each visual area: layout, header, content, sidebar, resources, manage
|
|
- No rules yet — just the section comments as placeholders
|
|
|
|
### {addon}.js
|
|
|
|
Skeleton contains:
|
|
- IIFE wrapper
|
|
- `initResourcePanels()` function — complete, this is the same in every addon
|
|
- One placeholder function per interactive area with a `// TODO` comment
|
|
- `init()` calling all functions
|
|
- DOMContentLoaded guard
|
|
|
|
The `initResourcePanels()` function is shared behavior. It is the same in every addon. Copy it exactly from the pilot — it is proven.
|
|
|
|
---
|
|
|
|
## Build Sequence
|
|
|
|
The operator will direct which addon to build first. The expected sequence based on the DSC development map is:
|
|
|
|
1. `vs01` — Vital Signs — because it is the entry point for both participants and attorneys
|
|
2. `dsc01` — DSC Categories — because it is the primary reference surface
|
|
3. `scn01` — Scenarios — because it depends on both Vital Signs and DSC context being established
|
|
|
|
**Each skeleton must be confirmed working — loading without errors, displaying the access wall or placeholder content correctly — before the next skeleton begins.**
|
|
|
|
---
|
|
|
|
## What the Operator Will Decide Before Each Skeleton Is Built
|
|
|
|
Before writing any skeleton file, discuss and confirm with the operator:
|
|
|
|
1. The exact route — the operator may have a different preference than what is proposed here
|
|
2. The access model — which privacy group gates participant access for this addon
|
|
3. The sidebar content — what resources and navigation the Widget shows
|
|
4. The config fields — whether any addon-specific configuration is needed beyond the standard fields
|
|
5. The spool contract — what the payload block contains for this addon's submissions
|
|
|
|
Do not assume these decisions are made because they appear in this document. This document proposes. The operator decides.
|
|
|
|
---
|
|
|
|
## What Not To Do
|
|
|
|
- Do not port the pilot `ds01` code. Read it as reference. Write the skeleton fresh.
|
|
- Do not add functional logic to the skeleton. Placeholders only.
|
|
- Do not generate all three skeletons at once. One at a time, confirmed working before the next begins.
|
|
- Do not create files that already exist in the repo. Read the repo first.
|
|
- Do not hardcode any value that belongs in `config.json`.
|
|
- Do not write inline styles or inline scripts.
|
|
- Do not exceed 500 lines in any PHP file. The skeleton should be well under that — if it is approaching 300 lines before any logic is added, something is wrong.
|