Add score template schema registry and documentation

CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased] - 2025-09-24
+### Added
+- Schema-validated score template registry with bundled `performance_health_v1` definition and FastAPI endpoints.
+- Automated score template tests covering registry usage and HTTP access.
+
+### Changed
+- Centralized SPOT documentation to include bundled templates and score templates.
+- API router registration now links in the score template router with governance metadata comments.
+- Added optional `DISABLE_REDIS_FOR_TESTS` and `DISABLE_DB_FOR_TESTS` flags so automated suites can bypass infrastructure services.
+
+### Fixed
+- Ensured tasklist/diagram governance artefacts exist for new functions.
+
+### Docs
+- Added score template function documentation, ERD assets, and schema overview with nb-NO localization.
+
 ## [3.1.0] - 2025-09-24
 
 ### Added

SPOT.md

@@ -0,0 +1,52 @@
+# SPOT – Security Assessment Platform
+
+**en:** Central hub for backend modules, schemas, and operational checklists that drive the assessment service.
+
+**nb-NO:** Sentral oversikt for backend-moduler, skjemaer og sjekklister som driver vurderingstjenesten.
+
+## Integration Plan – Score Template Expansion
+- [x] Align assessment template documentation with SPOT layout (migrate `docs/SPOT_Assessments.md`).
+- [x] Implement reusable score template schema validation + registry utilities.
+- [x] Expose score template summaries and definitions through FastAPI endpoints and automated tests.
+- [x] Update documentation set (function docs, tasklist, ERD, localization) and changelog for the new score template feature.
+
+## Function Catalog
+
+### Backend (Python/FastAPI)
+- <i class="fas fa-clipboard-check"></i> **Assessment Template Registry** — Bundled template loader & API. _(Function doc pending migration; tracked in integration plan.)_
+- <i class="fas fa-chart-gauge"></i> **Score Template Registry** — Schema-validated score template loader with FastAPI exposure. → `./docs/functions/score_template_registry.md`
+- <i class="fas fa-network-wired"></i> **API Router v1** — Aggregates versioned public/admin routers. → `./docs/functions/api_router_v1.md`
+- <i class="fas fa-cogs"></i> **Core Setup & Lifespan** — FastAPI factory & Redis pool orchestration with test bypass flag. → `./docs/functions/core_setup.md`
+
+#### Bundled Assessment Templates
+| ID | Version | Title | Notes |
+| --- | --- | --- | --- |
+| `course_gdpr_social_email_cookies_v1_no` | 1.1.0 | GDPR, sosial manipulering, e-post og cookies | JSON definition validated at load time |
+
+- Schema models: `src/app/schemas/assessment_template.py`
+- Template resources: `src/app/assessment_templates/definitions/*.json`
+- Registry module: `src/app/assessment_templates/registry.py`
+- API access: `GET /api/v1/assessment/schema`, `GET /api/v1/assessment/schema/{template_id}`
+
+### Frontend (HTML/JS)
+- Existing Vuexy-based assets (see `docs/index.md`) pending catalog alignment.
+
+### Database (PostgreSQL)
+- Core assessment schema coverage documented in `docs/Database/database_info.md`.
+
+### Infra/Provisioning
+- Docker compose stack with Supabase-compatible Postgres (`docker-compose.yml`).
+
+## Documentation Index (Referenced to avoid orphans)
+- `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `LICENSE.md`
+- Getting Started Guides → `docs/getting-started/*.md`
+- API Documentation → `docs/API_Documentation.md`
+- Authentication Flow → `docs/AUTHENTICATION_FLOW.md`
+- Assessment System Guide → `docs/Assessment_System_Guide.md`
+- User Flow Overview → `docs/USER_FLOW_COMPLETE.md`
+- Database Reference → `docs/Database/database_info.md`
+- Comprehensive User Guide Sections → `docs/user-guide/**`
+
+## Task Tracking
+- Dynamic tasklist lives at `./docs/tasks/tasklist.md`.
+

docs/erd.mmd

@@ -0,0 +1,5 @@
+erDiagram
+    SCORE_TEMPLATE ||--o{ SCORE_BUCKET : "qualifies"
+    SCORE_TEMPLATE ||--o{ SCORE_DIMENSION : "weights"
+    SCORE_DIMENSION ||--o{ SCORE_ITEM : "covers"
+    SCORE_TEMPLATE }o--|| SCORE_SCALE : "uses"

docs/functions/api_router_v1.md

@@ -0,0 +1,45 @@
+---
+langs: [en, nb-NO]
+lastUpdated: 2025-09-24
+---
+
+# <i class="fas fa-network-wired"></i> API Router v1 — Overview
+Aggregates all versioned public and admin FastAPI routers under the `/api/v1` namespace.
+
+**nb-NO:** Samler alle versjonerte offentlige og administrative FastAPI-rutere under `/api/v1`-navnerommet.
+
+Source paths:
+- `src/app/api/v1/__init__.py`
+
+**SPOT:** ./SPOT.md#function-catalog
+
+## API
+- Instantiates `fastapi.APIRouter(prefix="/v1")`.
+- Includes sub-routers for authentication, assessments, admin tooling, and the score template endpoints.
+- Exposed upstream via `src/app/api/__init__.py` as part of the main FastAPI application.
+
+## Design
+- Router order groups general endpoints first, followed by assessment flows, and finally admin-specific routes to keep documentation organized.
+- Sub-router inclusion retains their intrinsic prefixes (e.g. `/assessment`, `/score-templates`) for predictable URL paths.
+- File-level comment and SPOT linkage satisfy the single-SPOT governance rules.
+
+## Usage
+```python
+from app.api.v1 import router as v1_router
+
+app_router = APIRouter(prefix="/api")
+app_router.include_router(v1_router)
+```
+
+## Changelog
+### 2025-09-24
+- Documented router aggregation and added score template router inclusion.
+
+## Diagrams
+```mermaid
+flowchart TD
+    A[APIRouter /api/v1] --> B[/Auth Routers/]
+    A --> C[/Assessment Routers/]
+    A --> D[/Score Template Router/]
+    A --> E[/Admin Routers/]
+```

docs/functions/core_setup.md

@@ -0,0 +1,51 @@
+---
+langs: [en, nb-NO]
+lastUpdated: 2025-09-24
+---
+
+# <i class="fas fa-cogs"></i> Core Setup & Lifespan — Overview
+Manages application startup, Redis pool initialization, and router wiring helpers.
+
+**nb-NO:** Håndterer oppstart av applikasjonen, Redis-tilkoblinger og hjelpetjenester for rutere.
+
+Source paths:
+- `src/app/core/setup.py`
+
+**SPOT:** ./SPOT.md#function-catalog
+
+## API
+- `create_application(router, settings, ...) -> FastAPI`
+- `lifespan_factory(settings, create_tables_on_start=True)`
+- Redis helper coroutines (`create_redis_cache_pool`, `create_redis_queue_pool`, etc.)
+
+## Design
+- Uses mixin settings classes to decide which pools to initialize during startup.
+- Introduces `DISABLE_REDIS_FOR_TESTS` flag to bypass Redis connections for automated tests and offline development.
+- Adds `DISABLE_DB_FOR_TESTS` to skip database table creation during ephemeral test runs.
+- Keeps closing routines symmetric with startup hooks to avoid dangling connections.
+
+## Usage
+```python
+from app.core.setup import create_application, lifespan_factory
+from app.core.config import settings
+from app.api import router
+
+lifespan = lifespan_factory(settings)
+app = create_application(router=router, settings=settings, lifespan=lifespan)
+```
+
+Set `DISABLE_REDIS_FOR_TESTS=1` to skip Redis queue/cache/rate-limit connections during tests.
+
+## Changelog
+### 2025-09-24
+- Documented Redis bypass flag and linked module into SPOT.
+
+## Diagrams
+```mermaid
+flowchart TD
+    A[Startup] --> B{Redis disabled?}
+    B -- Yes --> C[Skip Redis pools]
+    B -- No --> D[Create cache/queue/rate-limit pools]
+    D --> E[Run migrations]
+    C --> E
+```

docs/functions/score_template_registry.md

@@ -0,0 +1,61 @@
+---
+langs: [en, nb-NO]
+lastUpdated: 2025-09-24
+---
+
+# <i class="fas fa-chart-gauge"></i> Score Template Registry — Overview
+Centralized loader and validator for qualitative score templates backed by JSON Schema and Pydantic models.
+
+**nb-NO:** Sentral innlasting og validering av skårmaler basert på JSON Schema og Pydantic-modeller.
+
+Source paths:
+- `src/app/score_templates/__init__.py`
+- `src/app/score_templates/registry.py`
+- `src/app/score_templates/schema.py`
+- `src/app/score_templates/validation.py`
+- `src/app/score_templates/definitions/performance_health_v1.json`
+- `src/app/api/v1/score_templates.py`
+
+**SPOT:** ./SPOT.md#function-catalog
+
+## API
+- Python: `list_score_templates() -> list[ScoreTemplateSummary]`
+- Python: `get_score_template(template_id: str) -> ScoreTemplateDefinition | None`
+- HTTP: `GET /api/v1/score-templates/`
+- HTTP: `GET /api/v1/score-templates/{template_id}`
+
+Responses use the `ScoreTemplateSummary` and `ScoreTemplateDefinition` Pydantic models to guarantee a consistent contract.
+
+## Design
+- Bundled templates live under `app.score_templates.definitions` and must satisfy `score_template.schema.json`.
+- `validate_template` enforces JSON Schema compliance plus semantic checks (weight sum, bucket coverage, tip alignment).
+- Registry cache (`functools.lru_cache`) avoids repeated disk reads while keeping a simple reload story for future extensibility.
+- API router mirrors the assessment template endpoints to keep the public surface predictable.
+
+## Usage
+```python
+from app.score_templates import list_score_templates
+
+summaries = list_score_templates()
+for summary in summaries:
+    print(summary.key, summary.dimension_count)
+```
+
+```shell
+$ curl http://localhost:8000/api/v1/score-templates/
+```
+
+## Changelog
+### 2025-09-24
+- Initial publication with schema validation, registry cache, FastAPI endpoints, and bundled performance template.
+
+## Diagrams
+```mermaid
+flowchart TD
+    A[Load JSON resource] --> B[validate_template]
+    B -->|ScoreTemplateDefinition| C{Registry cache}
+    C --> D[list_score_templates]
+    C --> E[get_score_template]
+    D --> F[/API list endpoint/]
+    E --> G[/API detail endpoint/]
+```

docs/schema.md

@@ -0,0 +1,25 @@
+---
+langs: [en, nb-NO]
+lastUpdated: 2025-09-24
+---
+
+# Data Model Overview
+
+**en:** Simplified entity diagram for score templates and related concepts.
+
+**nb-NO:** Forenklet enhetsdiagram for skårmaler og tilhørende begreper.
+
+![ERD](../public/erd.svg)
+
+<details>
+<summary>Mermaid fallback</summary>
+
+```mermaid
+erDiagram
+    SCORE_TEMPLATE ||--o{ SCORE_BUCKET : "qualifies"
+    SCORE_TEMPLATE ||--o{ SCORE_DIMENSION : "weights"
+    SCORE_DIMENSION ||--o{ SCORE_ITEM : "covers"
+    SCORE_TEMPLATE }o--|| SCORE_SCALE : "uses"
+```
+
+</details>

docs/tasks/tasklist.md

@@ -0,0 +1,13 @@
+# Dynamic Tasklist
+
+## Ongoing
+
+## Completed
+- [x] Tasklist file created
+- [x] Initialize tasklist
+- [x] Update docs & SPOT for `score_template_registry`; CHANGELOG [Unreleased]
+- [x] Verify diagrams exist for `score_template_registry` (Diagrams section)
+- [x] Update docs & SPOT for `api_router_v1`; CHANGELOG [Unreleased]
+- [x] Verify diagrams exist for `api_router_v1` (Diagrams section)
+- [x] Update docs & SPOT for `core_setup`; CHANGELOG [Unreleased]
+- [x] Verify diagrams exist for `core_setup` (Diagrams section)

pyproject.toml

@@ -18,6 +18,7 @@ dependencies = [
     "asyncpg>=0.29.0",
     "SQLAlchemy-Utils>=0.41.1",
     "python-jose>=3.3.0",
+    "jsonschema>=4.23.0",
     "SQLAlchemy>=2.0.25",
     "python-multipart>=0.0.9",
     "greenlet>=2.0.2",

src/app/api/v1/__init__.py

@@ -1,3 +1,4 @@
+# Docs: ./docs/functions/api_router_v1.md | SPOT: ./SPOT.md#function-catalog
 from fastapi import APIRouter
 
 from .login import router as login_router
@@ -17,6 +18,7 @@
 from .lead_capture import router as lead_capture_router
 from .password import router as password_router
 from .assessments import router as assessments_router
+from .score_templates import router as score_templates_router
 from .email import router as email_router
 
 # New comprehensive endpoints from migration file analysis
@@ -47,6 +49,7 @@
 
 # Assessment endpoints - accessible at /api/v1/assessment (singular to match API test console)
 router.include_router(assessments_router, prefix="/assessment", tags=["assessments"])
+router.include_router(score_templates_router)
 
 # Other endpoints with standard prefixes
 router.include_router(categories_router, prefix="/categories", tags=["categories"])