Development Documentation

API Documentation

API documentation is available in Postman. Import the collection from docs/datasets.postman_collection.json.

Oracle Database Instance

For local development, an Oracle XE 21c database runs in Docker via docker-compose.yaml. The instance:

• Runs on port 1521 (default Oracle port)
• Uses ORACLE_PASSWORD=oracle for system user
• Connects to database XE
• Initializes with scripts from scripts/oracle/init-scripts/
• Stores data in a persistent Docker volume

To verify the database is running:

docker-compose logs oracle-xe

Production Documentation

Overview

dregndrop-v2 is a web application for building pivot tables and data visualizations. Users interact through an embedded interface to select data fields and filters. These selections are sent to the backend, which builds SQL queries, fetches and processes data, and returns results as tables or charts.

System Architecture

Production Deployment

The application runs as a standalone service and is embedded in other sites via iframe.

Deployment Types

Open/Public Deployment

• Deploy web frontend and backend using Docker Compose
• Embed frontend as iframe in parent site
• No access controls

With Authorization (Private Portal)

• Enable authorization in server/config/config.prod.yaml and configure Redis for session management
• Application validates session cookies using Redis
• Note: Only authorization is handled here; authentication happens in the parent portal

Deployment Environments

Notes:

• Private instance: members.ecensus.gov.om
• Public instance: Internal Windows infrastructure, planned migration to Linux at ecensus.gov.om

For questions or support, contact the team.

Managing Metadata YAML

YAML Structure

The metadata YAML has two main sections:

• categories: Groups datasets and dashboards. Each dashboard id links to an Oracle view/materialized view
• tables: Defines columns, measures, default views, and filters for each dataset

Key fields:

• columns: Fields for the dataset. Each field must match an Oracle column
• measures: Aggregations (count, sum, average, etc.)
• default_view: Default columns and measures when opening a dataset
• filters: Default data filters
• Language support: Each table defined once per language; categories map both languages

Editing Columns

1. Find the table under tables:
2. Change column name: Update the name property
3. Remove column: Delete from columns: list
4. Add column: Add to columns: with field matching Oracle column

Adding Datasets/Dashboards

1. Under tables:, add entry with table key matching the exact Oracle view/materialized view name
2. List all fields with names matching Oracle columns
3. Define measures, default_view, and filters
4. Update relevant category under categories: and reference the new table/view
5. Provide table/view ID for each language in dashboard entry

Metadata Files by Environment

• Local development: server/metadata.yaml
• Private production: server/metadata.prod.yaml
• Public: server/metadata.public.yaml

After changes: Redeploy or reload backend to load new metadata.

Field Visibility

Fields marked measure_only: true are hidden in UI and used only for aggregations.

Column Ordering

The order in columns: list determines UI display order.

Managing Permissions

In private portals, user access is controlled by roles in server/permissions.yaml (or server/permissions.prod.yaml). Each role specifies allowed views/dashboards. Some roles have all access; others are restricted.

Permission Enforcement

The system checks user roles and displays only allowed datasets/dashboards per roleDashboardMap.

Updating Role Access

1. Edit server/permissions.yaml (or server/permissions.prod.yaml) under roleDashboardMap
2. Add or remove dataset/dashboard IDs per role
3. Use all for full access
4. Redeploy or reload backend for changes to take effect