Skip to content

Municipalities & departments

This page explains how to configure municipalities and their organizational structure.

Overview

The municipality model is the foundation of the platform's multi-tenant architecture. Each municipality has: - Geographic boundaries - Departments and staff - Vertical-specific configurations - Contact information

Municipality configuration

Creating a municipality

  1. Navigate to Municipalities → Municipalities in Django Admin.
  2. Click Add Municipality.
  3. Fill in the configuration:
Field Description
Name Official municipality name
Code Unique identifier (e.g., "LIS" for Lisbon)
Boundary Geographic boundary (MultiPolygon)
Email Contact email for the municipality
Phone Contact phone number
Address Physical address
Is Active Enable/disable the municipality

Geographic boundaries

The boundary field defines where this municipality has jurisdiction: - Used for auto-assigning occurrences by location - Determines which municipality "owns" a geographic point - Stored as PostGIS MultiPolygon (SRID 4326)

Setting up boundaries

  1. Use the map widget in Django Admin to draw the boundary
  2. Or import from GeoJSON/Shapefile
  3. Ensure boundaries don't overlap with other municipalities

Auto-assignment settings

Setting Description
Auto-assign occurrences Automatically assign submissions within boundaries

When enabled: - New occurrences are matched to municipality by location - Staff see only their municipality's records (by default) - Reports outside any boundary may go to a default or require manual assignment

Department structure

Creating departments

Departments organize staff and can have specific responsibilities:

  1. Navigate to Municipalities → Departments.
  2. Click Add Department.
  3. Configure:
Field Description
Municipality Parent municipality
Name Department name (e.g., "Public Works")
Code Unique code within municipality
Description What this department handles
Email Department contact email
Is Active Enable/disable

Department examples

Department Typical responsibilities
Public Works Infrastructure, roads, utilities
Parks & Recreation Parks, trails, public spaces
Environmental Services Waste, recycling, environmental issues
Transportation Traffic, parking, public transit
IT Services Technology, equipment
Administration General administration

Department permissions

Departments can have specific permissions for occurrence types:

  1. Navigate to Municipalities → Department Permissions.
  2. Create permission records linking departments to occurrence types.
  3. Set capabilities:
Permission Description
Can View See occurrences of this type
Can Edit Modify occurrence details
Can Assign Assign to other staff
Can Close Close/resolve occurrences
Can Create Actions Add actions/updates

Staff management

Municipality users

Staff are linked to municipalities through the MunicipalityUser profile:

  1. Create a Django user account.
  2. Navigate to Municipalities → Municipality Users.
  3. Create the profile:
Field Description
User Django user account
Municipality Which municipality they work for
Department Optional department assignment
Role Admin, Manager, Operator, or Viewer
Is Active Can access the system
Is Approved Has been approved to work

Role definitions

Role Capabilities
Administrator Full configuration access, all operations
Manager Configure workflows, view reports, manage staff assignments
Operator Work on records, update status, communicate
Viewer Read-only access to records

Category restrictions

Staff can be restricted to specific occurrence types:

  1. Edit the MunicipalityUser record.
  2. Set Allowed Occurrence Types.
  3. If empty: staff can access all types.
  4. If populated: staff can only access specified types.

This enables specialization (e.g., traffic team only sees traffic-related reports).

Cross-vertical considerations

Equipment assignments

Equipment can be assigned to specific municipalities: - Each Equipment record has a municipality field - Staff see equipment for their municipality - Cross-municipality equipment sharing requires appropriate permissions

Occupancy POIs

Points of Interest are linked to municipalities: - Each POI belongs to one municipality - Staff manage POIs for their municipality - Public dashboards show municipality-specific data

Dynamic forms

Forms can be configured per municipality: - Different intake forms for different municipalities - Shared forms with municipality-specific field mappings - Use case assignments can vary by municipality

Multi-language support

Department and municipality fields support translation: - Name and description fields can have translations - Uses Django's translation framework - Admin UI shows translated values based on user language

Behind the scenes (grounded in code)

  • Municipality model: apps/municipalities/models.py → Municipality
  • Department model: apps/municipalities/models.py → Department
  • Staff profile: apps/municipalities/models.py → MunicipalityUser
  • Permissions: apps/municipalities/models.py → DepartmentPermission
  • Geographic boundary: PostGIS MultiPolygonField (SRID 4326)
  • Admin: apps/municipalities/admin.py
  • API: apps/municipalities/views.py