About

Institutional Compass — version information, deployment architecture, and system guide.

Go to Home Documentation

🚀 Version: North 3.0

North 3.0 is the current production release of the Institutional Compass application, deployed on Google Cloud Platform with enterprise-grade infrastructure and enhanced capabilities.

Cloud Infrastructure

The application is hosted entirely on Google Cloud Platform (GCP) using the following services:
Important: North 3.0 does not require Google Cloud Storage. All diagram artifacts (PNG files) are stored directly in PostgreSQL as Base64-encoded strings in the session_data.artifacts JSONB column, eliminating external file storage dependencies and simplifying the architecture.

System Capabilities

North 3.0 provides the following core capabilities:

Technical Stack

Deployment URLs

Both URLs serve the same Cloud Run deployment with identical functionality and data access.

What is the Institutional Compass?

The Institutional Compass is an analytical framework for evaluating and visualizing institutional qualities across three core dimensions: Harmony, Discipline, and Excitement. In this application, the compass is implemented as a six-module workflow that starts with institutional definition and desired direction, moves through indicator collection and robust normalization, and concludes with visualization, validation against an aspirational "wish spot," policy planning, and final report generation.

Table of contents

Jump to a section:
How it works Core objects Module 1 Module 2 Module 3 Module 4 Module 5 Module 6 Key math Outputs

How it works (end-to-end)

The application is designed as a progressive chain of responsibilities. Early modules capture intent and meaning; middle modules capture measurements and normalize them; late modules create decision-friendly visuals and planning artifacts.
Practical note: stage submission order is enforced in places; later modules may assume earlier modules were submitted.

Core objects and concepts

Throughout the workflow, most data is stored per-session. Each module writes a "payload," and later modules read from it. The most important objects are:

Module 1 — Defining the Institution

Module 1 establishes the institutional context: identity, boundaries, key actors, and continuity criteria. The UI uses SMART-style prompts to help users be explicit about scope and meaning so later stages interpret indicators and policies against a stable definition.

Module 2 — Defining the Wish Spot

Module 2 captures both (a) qualitative meaning for Harmony, Discipline, and Excitement, and (b) a quantitative target in compass space. Qualitatively, the module collects words and associations that help define what each quality means in this institution's context. Quantitatively, it defines a wish spot as an arrow (length + rotation) and an ellipse tolerance region (Rx, Ry).

Module 3 — Data Collection & Screening

Module 3 collects the institution's indicators in a structured, repeatable way. Each indicator includes a rationale (why it matters), a search query (how to find benchmarks), and a data point (name, optional numeric value, notes, and a required source). Users can enter comparables manually or let the UI generate default comparables from the base value.

Module 4 — Data Analysis

Module 4 transforms raw indicator values into normalized compass vectors. It uses comparable sets to compute a robust normalized score (0..1), scales this to a readable length (0..10), and assigns a degree (0..359°) that positions the indicator within the compass' three-sector geometry. This stage also produces per-indicator coordinates and aggregate sector summaries used by Module 5.

Module 5 — Compass Visualization

Module 5 turns the computed vectors into three diagrams and validates the final arrow against the wish spot. It reads the analyzed results (sector arrows + final arrow), overlays the wish spot (arrow + ellipse tolerance), and classifies whether the outcome is inside the wish region, aligned-but-too-long/short, or misaligned.

Module 6 — Report Generation

Module 6 supports policy planning and final documentation. It suggests "aligning" indicators (near the wish direction) and "opposing" indicators (near the opposite direction), captures two policy narratives (Policy A to strengthen; Policy B to weaken), generates a dual-arrow projection visualization (current vs desired), and produces a final DOCX report for download.

Key math (high level)

The implementation uses a small number of recurring geometric and normalization steps. These are presented here for conceptual clarity (the application also stores intermediate results and logs during computation).
Wish spot: polar → Cartesian
X = L · cos(θ)
Y = L · sin(θ)

L = WishSpot_Arrow_Length
θ = WishSpot_Arrow_Rotation (deg)
Robust normalization (concept)
p = 1 / (1 + e^( -k · (x - m) ))

m = median(sample)
k = 4 / IQR(sample)
length0-10 = 10 · p
Wish validation: ellipse test
Translate: dx = x - cx, dy = y - cy
Rotate into ellipse frame
Test: (dx/rx)^2 + (dy/ry)^2 ≤ 1

inside = true if within tolerance

Outputs, artifacts, and exports

The application emphasizes portability and auditability. Most stages support JSON export/import; indicator datasets can be moved via CSV; visualizations are emitted as PNG artifacts; and the final report is a DOCX download.

This page describes the current North 3.0 release; wording and UI prompts may evolve as the system is refined.