Ripple-IQ

RippleIQ: institutional decision intelligence—enter a policy change, and it maps affected stakeholders, simulates 3 scenarios, flags hidden risks, scores confidence, and delivers an audit-ready report

Comment

What is RippleIQ?

Universities are complex ecosystems. When leadership considers a sweeping policy change — like shifting from a five-day to a four-day on-campus schedule — the second- and third-order consequences can be massive and completely unanticipated.

Who does it hurt? What breaks quietly? What happens to shuttle schedules, lab experiments running on continuous timers, faculty office hours, and student mental health?

RippleIQ answers those questions before the decision is made.

Inspiration

The idea came from a real friction point: institutional leaders — university presidents, provosts, academic senate committees — are expected to make high-stakes decisions affecting thousands of people, yet they rarely have structured tools to trace ripple effects across every stakeholder group before acting.

Spreadsheets miss second-order consequences. Consultants are slow and expensive. There was no lightweight, AI-augmented tool built specifically for the rhythm of academic governance.

RippleIQ is that tool.

How I Built It

The project is a full-stack application built across three layers:

Backend — FastAPI + Python

  • REST API with 20+ implemented endpoints covering the full decision lifecycle
  • SQLAlchemy 2.0 ORM against PostgreSQL (with SQLite for zero-config local dev)
  • Pydantic v2 schemas for strict input validation
  • Alembic database migrations
  • 40+ pytest tests covering core services
  • Docker Compose for one-command local setup

AI Analysis Engine — Deterministic Python Simulator

  • A rule-based, deterministic analyzer (mock_analyzer.py) — no external LLM API keys required
  • Fully reproducible and auditable: same input always produces the same analysis
  • Designed to be swapped for a live LLM backend without changing the API contract

Frontend — Next.js 14 (App Router)

  • Multi-step decision wizard: describe → add context → simulate → review scenarios → view recommendation → download report
  • Academic-grade design system: deep navy, slate, warm white
  • WCAG 2.1 AA accessibility compliance
  • Full decision detail flow: stakeholder impacts, risk register, scenario comparison, executive recommendation, and audit-ready Markdown report download

The decision flow:

  1. User describes a proposed policy change in plain language
  2. System identifies all affected stakeholder groups (students, faculty, labs, administration, transportation)
  3. Generates three comparative scenarios: as-written / modified-safer / limited-pilot
  4. Surfaces impacts, risks, and hidden assumptions for each scenario
  5. Assigns a confidence score with full explainability
  6. Produces an audit-ready Markdown report a leadership team can hand to a board

Core principle: human_review_required: true — RippleIQ is decision support, not a decision maker. The final call always belongs to a human.

Challenges I Faced

Planning discipline. The hardest part wasn't writing code — it was resisting the urge to write code before the system was properly designed. Writing the scope document, PRD, and technical spec before touching the editor forced me to think through the full decision flow end-to-end, including all the edge cases (what happens if a simulation fails? what if context data is missing? how do you handle a confidence score of 0?).

Deterministic AI without an LLM. Building a realistic simulation engine that didn't depend on any external API was genuinely hard. The mock analyzer needed to produce coherent, believable stakeholder impacts and risk assessments from structured input alone — which required careful rule design, not just prompt engineering.

Frontend ↔ Backend contract alignment. Keeping 20+ API endpoints, 11 database tables, Pydantic schemas, and a Next.js frontend synchronized required constant discipline. Any drift between the API contract and the frontend assumptions broke the demo. The docs/ folder (api-contract.md, database.md, frontend-requirements.md) was the single source of truth that kept everything coherent.

What I Learned

Plan before you build — really plan. Running the skills interview process before writing a single line of code changed the outcome dramatically. The AI didn't just write code; it asked hard questions that shaped a better product. By the time I opened the editor, I already knew exactly what I was building and why.

Audit trails matter from day one. Adding the audit_log table and human_review_required flag early made the system feel trustworthy. Decision support tools only work if the people using them trust the output — and trust comes from transparency, not just accuracy.

The deterministic-first approach is underrated. Building without an LLM dependency made the system faster, cheaper to run, fully testable, and easy to demo offline. When the live LLM integration comes, the architecture is already there — it's just a service swap.

What's Next

  • Plug in a live LLM (Gemini / GPT-4o) behind the same deterministic interface for open-ended decision analysis
  • Generalize beyond higher education: hospitals, city councils, school boards — any institution that needs structured foresight before a major policy shift
  • Real-time collaboration: multiple stakeholders annotating a decision analysis before it reaches the board
  • Export to PDF and presentation slide formats

Built With

Share this project:

Updates

Submission history