Skip to main content

​
Core Philosophy

This document defines the “Soul” of the Visita Intelligence Platform. It contains the fundamental principles that guide all development decisions and architectural choices.
For AI Agents: Before writing code, read this file. If a user request conflicts with these principles, warn them before proceeding.

​
1. What Visita Is NOT

Visita is NOT a social network. We explicitly reject the social media paradigm:
  • ❌ We do not optimize for engagement
  • ❌ We do not sell user attention
  • ❌ We do not “move fast and break things”
  • ❌ We do not use gamification or dopamine loops

​
2. What Visita IS

Visita is a Civic Intelligence Platform that:
  • ✅ Optimizes for awareness and participation
  • ✅ Sells intelligence tools, not ads
  • ✅ Builds critical infrastructure with care and deliberation
  • ✅ Empowers citizens with actionable local intelligence

​
3. The “Civic Window” Metaphor

The interface is a window into the user’s physical reality: 
┌─────────────────────────────────────────┐
│  Input: "Where am I?" (Location)        │
│  ↓                                       │
│  Output: "What is happening?" (Intelligence)
│  ↓                                       │
│  Action: "How can I help?" (Participation)
└─────────────────────────────────────────┘

​
Location → Intelligence → Participation

This three-step flow defines every interaction in Visita:
  1. Location Awareness: The system knows where you are (ward, municipality, province)
  2. Intelligence Delivery: Relevant information is surfaced based on your location
  3. Participation Opportunity: You’re empowered to act on what you’ve learned

​
4. Architecture Rules

​
A. The “Source of Truth” Rule

Postgres is King: All authoritative data lives in Supabase tables.
  • Supabase (PostgreSQL): The single source of truth
  • Algolia: A read-only cache for search and discovery
  • AI: A utility that summarizes or formats existing data, never generates facts
AI never creates new facts. It only processes, summarizes, or explains existing data from the database.

​
B. The “No-Magic” Auth Rule

Intent-Based Authentication:
  • Never force login on public pages
  • Only request authentication when user attempts a protected action
  • Always preserve user context (URL) after login
  • Use RequireAuth and RequireContext guards, not just middleware
Example Flow: 
User browses ward map (public)
→ Clicks "Join Ward" (requires auth)
→ Redirected to login with return_to=/ward/123
→ After login, returns to /ward/123

​
C. The “Graph” Geography Model

Wards are Atomic: The Ward is the base unit of civic organization and data aggregation.
Traditional Hierarchy (What we DON’T do): 
Country
  └── Province
      └── City
          └── Ward (lowest level)
Visita’s Graph Model (What we DO): 
        Ward A ←→ Business X
           ↓         ↓
        Ward B ←→ Business Y
           ↓
        Ward C
Key Principles:
  • Many-to-Many Relationships: A business can serve multiple wards
  • No Hardcoded Hierarchies: Use graph relationships, not rigid trees
  • Wards as Nodes: Wards connect to businesses, roads, incidents, people
  • Navigational Views: URLs are curated paths through the graph, not ownership hierarchies
Visita models reality as a graph. Pages are curated paths through that graph.

​
5. What NOT To Build (The Anti-Roadmap)

We explicitly avoid building features that contradict our core philosophy:
  • ❌ Global Chat: No unmoderated global feeds
  • ❌ Gamification: No badges, streaks, or dopamine loops
  • ❌ Chatbots as Navigation: AI is a feature, not the UI
  • ❌ Inline SQL: No raw SQL in components. Use RPCs or Typed Clients
  • ❌ Hardcoded Emails: All emails must go through /services/email

​
6. AI Governance

AI in Visita is an assistive, derived-intelligence system, not a decision-maker.

​
Guiding Principles

  1. AI is never a source of truth
  2. AI outputs are always derived, explainable, and replaceable
  3. AI must not silently influence civic, legal, or financial outcomes
  4. AI usage must be cost-controlled and auditable
  5. Humans retain ultimate authority over interpretation and action

​
Permitted AI Use Cases

✅ Summarization: Ward intelligence summaries, crime trend explanations ✅ Classification: Crime categorization, topic tagging ✅ Pattern Explanation: Explaining already-computed trends (NOT detecting new ones)

​
Prohibited AI Use Cases

❌ Generating or modifying source-of-truth data ❌ Making automated decisions affecting user permissions or payments ❌ Real-time moderation without human oversight ❌ Predictive policing or profiling ❌ Sentiment analysis on individuals
AI may explain patterns, but may not detect or infer new facts that are not present in the underlying data.

​
AI Output Data Model

All AI outputs must be stored as derived data with:
  • Clear labeling as AI-generated
  • Links to source data, timestamp, and model used
  • Safe to delete and regenerate at any time
AI outputs are cacheable artifacts, not permanent records.

​
7. Directory Structure Meaning

Understanding the codebase organization: 
/app/platform     → Authenticated, role-specific dashboards
/app/marketing    → Public landing pages (SEO optimized)
/services         → Infrastructure code (Email, AI, Payments) - Provider Agnostic
/components/ui    → Dumb, reusable UI atoms (shadcn)
/components/business → Smart, domain-specific logic

​
8. Technical Stack (Strict)

We maintain strict adherence to our technology choices:
  • Framework: Next.js 14+ (App Router)
  • Language: TypeScript (Strict mode)
  • Database: Supabase (PostgreSQL)
  • Auth: Supabase Auth (SSR)
  • Styling: Tailwind CSS + shadcn/ui
  • Maps: Leaflet (via react-leaflet)
  • Search: Algolia (Discovery layer only)
  • Email: Mailgun (via /services/email)

​
9. AI Coding Instructions

When contributing to Visita:
  1. Check Context: Before editing a file, check ROADMAP.md for active phases
  2. Use Services: Do not import 3rd party SDKs directly into UI components. Use the /services layer
  3. Type Everything: No any. Create interfaces in /types
  4. Mobile First: Always verify responsive classes (md:, lg:)

​
Summary

AI in Visita is a lens, not a judge. It assists understanding, but never replaces accountability.
This philosophy exists to ensure we build technology that strengthens trust rather than eroding it. Every feature, every line of code, and every architectural decision should align with these principles.
Next Steps: