/home/techb158/trellopowerup.abdallabala.com/docs
Edit: /home/techb158/trellopowerup.abdallabala.com/docs/31-trello-powerup-implementation-guide.md (7608B)
# Trello Power-Up Implementation Guide
Status: living guide
Current version: 0.4.5
Last updated: July 7, 2026
This guide records the Trello Power-Up work completed so far. Keep this file updated as new features are added, then use it as the final documentation guide when the build is complete.
## Goal
The Power-Up applies the COSMIC AI-Risk methodology directly inside Trello. It lets a team assess AI project risk from a card, save assessment history, review score trends, see board-level analytics, export evidence, and triage cards that need risk review.
## Main Files
| Area | Files |
| --- | --- |
| API server | `src/server.js` |
| Risk scoring | `src/riskEngine.js` |
| Assessment analytics, trends, exports, review queue | `src/assessmentAnalytics.js` |
| JSON persistence | `src/store.js` |
| Trello Power-Up capabilities | `public/powerup.js` |
| Assessment modal | `public/risk-modal.js`, `public/risk-modal.html` |
| Card back section | `public/card-section.js`, `public/card-section.html` |
| Board dashboard | `public/board-dashboard.js`, `public/board-dashboard.html` |
| Settings | `public/settings.js`, `public/settings.html` |
| Shared frontend helpers/styles | `public/client-utils.js`, `public/styles.css` |
| API contract | `openapi.yaml` |
| Tests and smoke test | `test/*.test.mjs`, `scripts/smoke-test.mjs` |
## Features Completed
### 1. Edit Existing Assessment and Risk History
- Latest assessment is loaded back into the assessment modal.
- Each save creates a new assessment history entry.
- Card history is returned newest first.
- Score trend metadata is calculated for each assessment:
- `previousScore`
- `scoreDelta`
- `trend`: `new`, `improved`, `worse`, or `unchanged`
- Card back section shows an expandable assessment history timeline.
### 2. JSON-Backed Local Persistence
- Replaced in-memory-only storage with JSON file persistence.
- Default store path is `./data/store.json`.
- Store path can be overridden with `COSMIC_STORE_FILE`.
- Health endpoint reports store mode, file path, and object counts.
- `data/` is ignored because it contains local runtime data.
### 3. Board Dashboard and Exports
- Board dashboard summarizes latest assessment per card.
- Dashboard includes risk distribution, average score, deployment blocked count, trend snapshot, last assessed context, and review-needed count.
- Filters support search, risk status, gate status, trend, and review state.
- Board exports are available as JSON and CSV:
- `/api/boards/{boardId}/export.json`
- `/api/boards/{boardId}/export.csv`
### 4. Review Queue Workflow
- Review signal is generated from latest assessment state.
- A card needs review when:
- deployment gate is blocked
- risk score worsened
- assessment is stale
- Stale threshold is configured with `COSMIC_REVIEW_STALE_DAYS` and defaults to `30`.
- Review signal includes:
- `needed`
- `reasons`
- `actions`
- `stale`
- `ageDays`
- `staleAfterDays`
- Recommended actions are generated from review reasons.
- Dedicated review queue endpoint returns only cards needing review:
- `/api/boards/{boardId}/review-queue`
- Focused review queue CSV export:
- `/api/boards/{boardId}/review-queue.csv`
- Dashboard includes a Review Queue panel with a queue export button.
- Trello card badges and card-detail badges show review-needed status.
- Card back and modal show review reasons and next actions.
### 5. Trello Workflow Integrations
- Trello Power-Up supports board button, card button, card badges, card-detail badges, settings, and card back section.
- Assessment modal saves COSMIC assessment data to the API.
- Optional Trello label synchronization adds COSMIC labels for risk status and gate status.
- Mitigation checklist can be created on a card.
- Mitigation completeness can be synced from the `COSMIC Risk Mitigation` checklist.
- Assessment summary comments can be posted to Trello cards.
### 6. Templates and Defaults
- Board settings support default typology, lifecycle phase, and measurement maturity.
- New assessments use board defaults when no saved assessment exists.
- Risk templates are available for common AI risks:
- data quality
- model drift
- bias/fairness
- deployment rollback
- legal/ethical review
## API Endpoints
| Method | Endpoint | Purpose |
| --- | --- | --- |
| GET | `/api/health` | Service status and store metadata |
| GET | `/api/taxonomy` | COSMIC reference taxonomy |
| POST | `/api/risks/score` | Score without saving |
| POST | `/api/boards/{boardId}` | Upsert board metadata |
| POST | `/api/cards/{cardId}` | Upsert card metadata |
| POST | `/api/boards/{boardId}/cards/{cardId}/assessments` | Save card assessment |
| DELETE | `/api/boards/{boardId}/cards/{cardId}/assessments` | Remove a card assessment history and clear it from dashboard results |
| GET | `/api/boards/{boardId}/cards/{cardId}/assessments/latest` | Read latest card assessment scoped to the active board |
| GET | `/api/cards/{cardId}/assessments/latest` | Read latest card assessment |
| GET | `/api/cards/{cardId}/assessments` | Read card assessment history |
| GET | `/api/boards/{boardId}/summary` | Board analytics summary |
| GET | `/api/boards/{boardId}/review-queue` | Review-needed card queue |
| GET | `/api/boards/{boardId}/review-queue.csv` | Focused review queue CSV |
| GET | `/api/boards/{boardId}/export.json` | Board evidence package JSON |
| GET | `/api/boards/{boardId}/export.csv` | Board evidence package CSV |
## Configuration
```env
PORT=3000
PUBLIC_BASE_URL=https://your-public-powerup-domain.example.com
TRELLO_API_KEY=replace_with_power_up_api_key
TRELLO_APP_NAME=COSMIC AI-Risk Management
ALLOWED_ORIGINS=https://trello.com,https://*.trello.com,http://localhost:3000
COSMIC_STORE_FILE=./data/store.json
COSMIC_REVIEW_STALE_DAYS=30
```
## Validation Commands
Run static checks:
```bash
npm run lint
```
Run unit tests:
```bash
npm test
```
Run smoke test while the server is running:
```bash
npm run smoke
```
Current validation status:
- `npm run lint` passes.
- `npm test` passes with 9 tests.
- `npm run smoke` passes with version `0.4.5`.
- Smoke test verifies health, scoring, save assessment, board summary, review queue, review queue CSV, JSON export, and CSV export.
## Test Coverage Added
- Risk engine scoring and gate behavior.
- Assessment history ordering.
- Review signal generation for blocked, worsened, and stale assessments.
- Board summary review counts.
- Board CSV review fields.
- Review queue filtering and urgency ordering.
- Review queue CSV export.
## VPS Deployment
A VPS deployment guide is available at docs/32-vps-deployment-guide.md. It covers Docker Compose, .env, Nginx, HTTPS, and Trello Power-Up admin setup.
## Current Known Constraints
- JSON file storage is suitable for local prototype validation, not multi-user production.
- Production should replace JSON storage with a database such as PostgreSQL.
- Trello live behavior requires public HTTPS hosting and a real Power-Up API key.
- Automated tests do not call live Trello APIs.
- Review stale-age calculation depends on assessment `createdAt` timestamps.
## Final Documentation Checklist
Before calling the project done, update this guide with:
- Final version number.
- Final feature list.
- Final validation output.
- Screens or demo notes if needed.
- Any production deployment notes.
- Any known limitations and future work.