CanuckDUCK Developer Framework — Recommendations and Build Roadmap

CanuckDUCK Developer Framework — Recommendations and Build Roadmap

Marker: CDK-DEVELOPER-FRAMEWORK-RECOMMENDATIONS-V0-1

Status: Recommendation document. This translates the initial Developer Framework concept into a concrete development program.

Executive recommendation

CanuckDUCK should formalize its current Drupal module ecosystem into a CanuckDUCK Module SDK: a documented civic-development framework with a module manifest, starter templates, validation tooling, approved APIs, and a review process. The project should not begin as a new programming language. It should begin as a Drupal-native framework with a declarative CanuckDUCK manifest. If the manifest proves useful, it can evolve into a civic DSL over time.

Recommended positioning

CanuckDUCK Developer Framework is a Drupal-based civic application framework for building approved modules that understand Canadian jurisdiction, CanuckDUCK platform surfaces, privacy minimization, RIPPLE graph context, Consensus drafting, Pond discussion, and AI review boundaries.

Core principle

Drupal provides the programming substrate. CanuckDUCK provides the civic contract.

Recommendation 1 — Create a canonical SDK repo

Create a Forgejo repository named canuckduck-module-sdk. Pond should carry developer-facing explanations and discussions, but the machine-readable assets should live in Git.

canuckduck-module-sdk/
  README.md
  docs/
    getting-started.md
    module-contract.md
    privacy-classes.md
    approved-apis.md
    ripple-integration.md
    consensus-integration.md
    pond-integration.md
    ai-boundaries.md
    review-process.md
  schemas/
    canuckduck.module.schema.json
    civic-artifact.schema.json
    ai-workflow.schema.json
  templates/
    cdk_example_block/
    cdk_example_route/
    cdk_example_public_data_widget/
    cdk_example_consensus_draft/
    cdk_example_ripple_viewer/
  tools/
    cdk-module-validate
    cdk-module-scaffold
  tests/

Recommendation 2 — Define canuckduck.module.yml

Each CanuckDUCK-aware module should include a manifest declaring civic intent, platform surfaces, data access, privacy class, AI use, and RIPPLE behavior.

canuckduck:
  schema_version: 0.1
  module:
    machine_name: cdk_example_public_data_widget
    type: civic_feature
    status: experimental
  civic:
    domains:
      - transportation
      - accessibility
    jurisdictions:
      supports:
        - municipal
        - provincial
  surfaces:
    pond:
      reads_public_content: true
      writes_content: false
    consensus:
      creates_draft_questions: true
      publishes_questions: false
    ducklings:
      enabled: false
    nest:
      aggregate_metrics_only: true
    continuum:
      enabled: false
  data:
    stores_personal_data: false
    stores_minor_data: false
    direct_database_access: false
  ripple:
    reads_context: true
    proposes_changes: false
    writes_directly: false
  ai:
    uses_ai: false
    requires_review: false
  review:
    required_lanes:
      - code
      - permissions
      - privacy

Recommendation 3 — Start with public/read-only modules

The first development lane should avoid private data, minors, account authority, payments, and direct graph mutation. This lets CanuckDUCK learn the framework shape without putting trust boundaries at risk.

Recommendation 4 — Define approved APIs before expanding contributors

Third-party modules should integrate through approved CanuckDUCK services rather than direct database queries or ad-hoc calls. Initial API/service categories should include:

• Geography service: resolve country/province/municipality/community scope and canonical paths.
• Forum/topic service: locate Pond topics and safe public forum context.
• Metadata service: apply controlled civic metadata and canonical IDs.
• Consensus draft service: create disabled/draft questions or polls only.
• RIPPLE context service: read graph context without direct mutation.
• Audit/logging service: record module actions consistently.
• AI request service: route only approved AI surfaces through policy-gated providers.

Recommendation 5 — Build validators early

The validator should reject common unsafe patterns before human review:

• Manifest missing or schema-invalid.
• Declared privacy class conflicts with code behavior.
• Direct database access where prohibited.
• Unreviewed external HTTP calls.
• Direct graph writes.
• AI use without declared route and review lane.
• Ducklings/minor-data surfaces without explicit platform approval.
• Permissions that expose admin or private functions to anonymous/authenticated users.

Recommendation 6 — Treat the manifest as the future DSL

The manifest should start as YAML/JSON schema, not a custom language. Over time, it can grow into a civic DSL for defining modules, civic artifacts, AI workflows, Consensus question patterns, and RIPPLE bindings.

Possible future manifest families:

• canuckduck.module.yml — module permission and integration declaration.
• civic-stream.yml — topic stream definition across Pond, Consensus, podcast, and RIPPLE.
• consensus-question.yml — neutral poll/question draft definition.
• ripple-binding.yml — graph read/proposal/write contract.
• ai-workflow.yml — AI persona input/output/review declaration.

Recommendation 7 — Publish docs in Pond, keep canonical code in Forgejo

Pond should be the living discussion and developer-facing knowledge home. Forgejo should remain canonical for schemas, templates, examples, validators, and tests. This keeps public documentation accessible while preserving proper software version control.

Recommended build sequence

1. Framework inventory: inspect current cdk_* and pond_* modules and identify reusable patterns.
2. SDK skeleton: create canuckduck-module-sdk with docs, schemas, templates, tools, and tests.
3. Manifest schema v0.1: define the minimum viable canuckduck.module.yml.
4. Starter template: create a simple Drupal module template with route, block, service, permissions, README, tests, and manifest.
5. Validator v0.1: validate manifest structure and obvious safety violations.
6. Pilot module: build one read-only public civic-data module using the template.
7. Review checklist: formalize code, permissions, privacy, AI, graph, and deployment review lanes.
8. Docs mirror: publish the getting-started guide and module contract in this forum.

Recommended first pilot

The first pilot should be boring and safe: a public civic-data viewer or dashboard. It should prove module declaration, route/block rendering, geography binding, permissions, uninstall behavior, manifest validation, and documentation without touching private data, account authority, minors, AI authority, or direct graph writes.

Good candidates:

• Municipal public-service directory viewer.
• Public meeting/event listing widget.
• Read-only RIPPLE topic context panel.
• Consensus draft-question example that creates disabled/draft questions only.

Acceptance criteria for v0.1

• A developer can scaffold a new CanuckDUCK-aware Drupal module from a template.
• The module includes a valid canuckduck.module.yml.
• The validator can pass/fail the manifest and report actionable errors.
• The starter module installs, renders one safe public feature, and uninstalls cleanly.
• The documentation explains what surfaces the module may touch and what is prohibited.
• The first pilot module proves the workflow end to end.

Decision requested

Approve the v0.1 development lane: create the SDK skeleton, define the initial manifest schema, build the starter template and validator, then run a low-risk pilot module through the process.