Skip to main content

​
Overview

OpenCouncil’s consultation module provides a comprehensive tool for local governments to conduct public consultations on regulatory texts. Citizens can view regulations, explore geographic areas on interactive maps, and provide feedback on specific articles and locations.

​
Core concepts

The consultation system is built around JSON-based regulation documents that combine textual content with geographic data.

Regulation

Structured document with chapters, articles, and references

Geographic areas

Points, circles, and polygons organized in geosets

References

Cross-links between text and locations using {REF:id} syntax

​
Regulation structure

Regulations follow a hierarchical structure defined by a JSON schema:
1

Chapters

Top-level sections with introductory text and articlesExample: “General Provisions”, “Traffic Rules”, “Parking Regulations”
2

Articles

Individual regulation items with markdown contentExample: “Article 5: Speed Limits in Pedestrian Zones”
3

Geographic areas

Organized in geosets (groups of related areas)Example: “prohibited_areas” geoset containing archaeological sites and hills
4

Cross-references

Links between text and other elementsExample: {REF:prohibited_areas} in article text links to the map areas

​
User experience

Citizens interact with consultations through a clean, mobile-first interface.

​
View modes

Features:
  • Full-screen interactive map
  • Overlay UI for layer control
  • Hierarchical geoset selection
  • Toggle controls for areas
  • Detail panel for selected areas
  • Mobile-optimized with collapsible UI
Use case: Exploring geographic boundaries and restrictions
A floating action button in the bottom right allows users to toggle between views with a single tap.

​
Reference system

Text can reference other parts of the regulation: 
Scooters are prohibited in {REF:prohibited_areas}, including archaeological sites and sensitive hills.
Clicking a reference navigates users to the appropriate view (text or map) and highlights the referenced element.

​
Data model

​
Consultation model

prisma/schema.prisma
model Consultation {
  id        String   @id @default(cuid())
  name      String
  jsonUrl   String   // URL to the regulation JSON file
  endDate   DateTime
  isActive  Boolean  @default(true)
  
  city      City     @relation(fields: [cityId], references: [id], onDelete: Cascade)
  cityId    String
  
  comments  ConsultationComment[]
  
  @@index([cityId, isActive])
  @@index([isActive, endDate])
}

​
Comment model

prisma/schema.prisma
model ConsultationComment {
  id            String   @id @default(cuid())
  body          String   @db.Text
  entityType    ConsultationCommentEntityType
  entityId      String
  
  user          User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  userId        String
  
  consultation  Consultation @relation(fields: [consultationId], references: [id], onDelete: Cascade)
  consultationId String
  
  upvotes       ConsultationCommentUpvote[]
  
  @@index([consultationId, entityType, entityId])
}

enum ConsultationCommentEntityType {
  CHAPTER
  ARTICLE
  GEOSET
  GEOMETRY
}
Every important element has a shareable permalink:
/[cityId]/consultations/[consultationId]Defaults to showing the map view
/[cityId]/consultations/[consultationId]/mapDirect link to interactive map
/[cityId]/consultations/[consultationId]#chapter-[chapterId]Scrolls to specific chapter in document view
/[cityId]/consultations/[consultationId]#article-[articleId]Highlights specific article
/[cityId]/consultations/[consultationId]/map#geoset-[geosetId]Shows specific geographic area group
/[cityId]/consultations/[consultationId]/map#geometry-[geometryId]Focuses on specific polygon or point
Elements with permalinks display a clickable icon:
  • Hover: Shows “Copy link” tooltip
  • Click: Copies link to clipboard
  • Feedback: “Ο σύνδεσμος αντιγράφηκε” confirmation message

​
Public feedback system

Citizens can comment on specific elements:

Text comments

  • Regulation chapters
  • Individual articles

Geographic comments

  • Geosets (area groups)
  • Specific locations/boundaries

​
Comment features

1

Authentication

Users must be logged in to comment
2

Rich text

Comments support markdown formatting
3

Upvoting

Other users can upvote comments to prioritize feedback
4

Moderation

Municipal admins can review and moderate comments

​
Map interface

The map view provides powerful visualization and interaction:

​
Layer control

  • Top level: Geoset groups (e.g., “Prohibited Areas”)
  • Second level: Individual areas within each geoset
  • Toggle controls for visibility
  • Visual distinction between types
  • Collapsible UI behind a button
  • Touch-friendly controls
  • Responsive layout
  • Maximizes map visibility

​
Detail panel

Sliding panel interface for viewing area details:
  • Displays geoset/area information
  • Shows related regulation text
  • Integrated commenting system
  • Smooth transitions

​
Example: Athens scooter regulation

The initial implementation demonstrates the system with Athens’ electric scooter regulation:

​
Content structure

  • Purpose and scope
  • Definitions (e-scooter, user, parking zone)
  • Age and licensing requirements

​
Geographic elements

{
  "id": "prohibited_areas",
  "name": "Prohibited Areas",
  "geometries": [
    {
      "id": "acropolis",
      "name": "Acropolis Archaeological Site",
      "geojson": { "type": "Polygon", ... }
    },
    {
      "id": "lycabettus_hill",
      "name": "Lycabettus Hill",
      "geojson": { "type": "Polygon", ... }
    }
  ]
}

​
Administrator tools

Super administrators have access to specialized tools for consultation management.

​
Map-based geolocation editor

A comprehensive editing interface for converting textual location descriptions into GeoJSON:
Problem: Many regulations define boundaries textually (e.g., “the area enclosed by streets A, B, and C”) rather than with coordinates.Solution: In-map drawing tools with real-time preview.

​
Editor features

1

Access control

  • Only visible to super administrators
  • Toggle button in layer controls panel
  • “Λειτουργία Επεξεργασίας” (Editing Mode)
2

Visual status system

  • ✓ Original data exists
  • 💾 Locally saved edits
  • ⚠️ Missing geometry
  • 🎯 Selected for editing
3

Contextual help

  • Textual definitions displayed during editing
  • Auto-zoom to geometry location
  • Street labels for orientation
4

Drawing tools

  • Point mode: Single-click location markers
  • Polygon mode: Multi-click boundary drawing
  • Visual feedback during drawing
  • Powered by Mapbox GL Draw
5

Local persistence

  • Changes saved to browser localStorage
  • Real-time preview on map
  • Blue styling for edited geometries
  • No server changes until export
6

Export workflow

  • “Εξαγωγή Regulation.json” button
  • Merges local edits with original data
  • Downloads complete production-ready JSON
  • Shows count of edited geometries
  • Timestamped filename for versioning

​
Editing workflow

Click the editing toggle to activate:
  • Street name labels appear
  • Edit buttons show next to geometries
  • Drawing tools become available
Click edit button (✏️) next to any geometry:
  • Map auto-zooms to location (if coordinates exist)
  • Geometry entry highlighted in blue
  • Textual definition displayed
  • Drawing mode activated
Choose drawing mode and create shape:
  • Points: Single click
  • Polygons: Multiple clicks, auto-close
  • Visual feedback during drawing
Geometry immediately:
  • Saved to localStorage
  • Displayed on map (blue styling)
  • Marked with save icon (💾)
Click export button to:
  • Merge all edits with original
  • Download regulation.json
  • Use in production

​
Implementation notes

​
JSON schema

Regulations must follow the defined schema: 
./json-schemas/regulation.schema.json
Validate your regulation JSON against this schema before uploading.

​
City feature flag

consultationsEnabled Boolean @default(false)
Cities must have this flag enabled to support consultations.

​
Regulation storage

Regulation JSON files are stored externally (e.g., S3, CDN) and referenced by URL in the Consultation.jsonUrl field.

​
Future features

Multi-regulation support

Support multiple active consultations per city for different policies

Version comparison

Tools to compare different versions of regulations and track changes

Analytics dashboard

Track citizen engagement, popular sections, and comment patterns

Export capabilities

Generate reports of public feedback for municipal review

​
Best practices

Organize regulations into logical chapters and articles before defining geographic areas.
Choose meaningful IDs for references: prohibited_areas not area1.
Always include textual boundary descriptions even when GeoJSON exists.
Ensure map controls and navigation work well on mobile devices.
Establish a process for reviewing and responding to citizen feedback.

​
File reference

Key implementation files

  • prisma/schema.prisma - Consultation models (lines 856-918)
  • docs/consultations.prd.md - Detailed PRD
  • json-schemas/regulation.schema.json - Regulation JSON schema
  • Map editor implementation (to be created)

Build docs developers (and LLMs) love

Get started for freeTalk to us