Declarations & Legal Compliance Engine

The Declarations & Legal Compliance Engine manages the formal accession, statutory verification, and democratic governance processes required for Polish Energy Cooperatives (Spółdzielnie Energetyczne) under the Ministry of Climate and Environment regulatory framework.

---

Functions Matrix (10 Functions)

Function Name	Inbound Trigger	Core Responsibility
get-company-declaration-schema	Client GET	Fetches dynamic JSON form schema defined by cooperative
approve-declaration-schema	Admin POST	Board approval of schema revisions before public availability
get-member-declaration	Client GET	Retrieves declaration state, verification timeline, and attachments
submit-member-declaration	Member POST	Submits formal accession declaration into approval queue
update-member-declaration	Member PATCH	Updates form fields following a correction request
review-member-declaration	Board Officer POST	Transitions declaration to APPROVED, REJECTED, or CORRECTION_REQUIRED
upload-declaration	Multipart POST	Uploads signed physical scans or digital signatures to declarations bucket
generate-resolution-document	Admin POST	Renders statutory voting resolution documents (Uchwały)
generate-prefilled-docx	Client POST	Injects member/installation parameters into .docx legal contracts
docx-to-html	Client POST	Converts .docx legal templates into responsive web preview HTML

---

Member Declaration Lifecycle

stateDiagram-v2
    [*] --> Draft: Member opens accession wizard
    Draft --> Submitted: submit-member-declaration
    Submitted --> UnderReview: Board assigns inspector
    
    UnderReview --> CorrectionRequired: review-member-declaration (CORRECTION)
    CorrectionRequired --> Submitted: update-member-declaration
    
    UnderReview --> Approved: review-member-declaration (APPROVE)
    UnderReview --> Rejected: review-member-declaration (REJECT)
    
    Approved --> ResolutionGenerated: generate-resolution-document
    ResolutionGenerated --> ActiveMember: Accession Finalized

---

Dynamic Declaration Schemas

Energy cooperatives can customize accession questionnaire fields (e.g. asking for heat pump capacity, building insulation level, or EV charger specs) without code deployments.

get-company-declaration-schema Schema Format

{
  "coop_id": "b1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "version": 3,
  "status": "PUBLISHED",
  "fields": [
    {
      "id": "ppe_number",
      "label": "Numer PPE (Punkt Poboru Energii)",
      "type": "string",
      "required": true,
      "validation_regex": "^PL[0-9]{16}$"
    },
    {
      "id": "pv_installed_kwp",
      "label": "Moc zainstalowana PV (kWp)",
      "type": "number",
      "min": 0,
      "max": 500,
      "required": true
    },
    {
      "id": "has_battery_storage",
      "label": "Czy posiadasz magazyn energii?",
      "type": "boolean",
      "required": false
    }
  ]
}

---

Document Generation Engine

1. generate-prefilled-docx

• Input: Template ID (.docx stored in declarations bucket) and JSON parameter map.
• Engine: High-speed AST token replacer that replaces tags such as {{member_name}}, {{pesel}}, {{ppe_number}}, and {{coop_name}}.
• Output: Generated Word document saved to storage bucket with secure download link.

2. generate-resolution-document

• Creates formal voting resolutions pursuant to the Polish Act on Cooperatives (Prawo spółdzielcze).
• Generates audit stamps with SHA-256 integrity hashes of voting tallies and member signature blocks.

3. docx-to-html

• Lightweight Deno converter extracting formatting, tables, lists, and signature blocks from .docx structures.
• Enables native in-app document viewing inside the Flutter app without requiring external document viewers.