System Architecture Overview

What Is Prism

Prism is a commercial real estate (CRE) intelligence platform for industrial property markets. It provides a centralized system for tracking buildings, lease comparables (comps), tenant-in-market activity (TIMs), ownership, brokerage relationships, analytics, and reporting — all within a multi-tenant, organization-isolated environment.

High-Level Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                            End Users                                     │
│                   (Browsers / BI Tools / API Clients)                    │
└─────────────────────────────┬────────────────────────────────────────────┘
                              │
                    ┌─────────▼──────────┐
                    │   Cloudflare Edge   │  ← TLS termination, WAF, caching
                    │   (CDN + Proxy)     │
                    └──┬──────────────┬───┘
                       │              │
          ┌────────────▼──┐    ┌──────▼──────────┐
          │  Cloudflare   │    │  Render          │
          │  Pages        │    │  (Go Backend)    │
          │  (Frontend)   │    │  Port 8080       │
          └───────────────┘    └──────┬───────────┘
                                      │
                         ┌────────────┼────────────┐
                         │            │            │
                  ┌──────▼──┐  ┌─────▼────┐ ┌─────▼─────┐
                  │ Postgres │  │  Redis   │ │  Clerk    │
                  │ + PostGIS│  │ (Cache)  │ │  (Auth)   │
                  │ (Supabase│  │ (Upstash)│ │  (JWT)    │
                  │  / RDS)  │  │          │ │           │
                  └──────────┘  └──────────┘ └───────────┘

Service Boundaries

Tech Stack

Frontend

Backend

Database

Infrastructure

Backend Architecture Pattern

The Go backend follows Clean Architecture (Ports & Adapters) with strict layering:

┌─────────────────────────────────────────────────────────────┐
│                    HTTP Layer (Handler)                      │
│  - Parse HTTP requests, validate input format               │
│  - Call service layer                                       │
│  - Format HTTP responses                                    │
│  - NO business logic                                        │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                   Service Layer (Business Logic)            │
│  - All business rules and validation                       │
│  - Orchestrate multiple repositories                       │
│  - Cache management                                        │
│  - NO HTTP knowledge, NO SQL queries                       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│              Repository Layer (Data Access)                  │
│  - SQL queries and data mapping                            │
│  - Interface-based (swappable)                             │
│  - NO business logic                                       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                    Database (PostgreSQL)                     │
└─────────────────────────────────────────────────────────────┘

Dependency Rule: Source code dependencies point inward only. Inner layers never depend on outer layers. Services depend on repository interfaces, not implementations.

Cross-Cutting Concerns

Frontend Architecture Pattern

The frontend follows a module-based architecture organized by feature domain:

frontend/src/
├── app/                    # App shell, providers, global styles
├── modules/                # Feature modules (one per domain)
│   ├── buildings/          # Building search, detail, edit
│   ├── comps/              # Comp lease search, detail, edit
│   ├── tims/               # TIM search, detail, edit
│   ├── dashboard/          # Main dashboard
│   ├── map/                # Explore map (multi-layer)
│   ├── analytics/          # Vacancy, absorption, pipeline, inventory
│   ├── operations/         # Needs review, missing data, recent changes
│   ├── data/               # Owners, brokers, leasing cos, reports, parks
│   ├── admin/              # Imports, errors, system setup, data export
│   └── lookups/            # Shared lookup data (regions, corridors, etc.)
├── shared/                 # Cross-module shared code
│   ├── api/                # Typed API client, query keys, error handling
│   ├── ui/                 # Shared UI components
│   ├── hooks/              # Shared hooks
│   ├── map/                # Shared map utilities
│   └── utils/              # Formatting, validation utilities
└── test/                   # Test setup and utilities

Key Frontend Patterns

• Server state: TanStack Query for all API data (no global stores)
• Form state: React Hook Form + Zod schemas
• URL state: Filter/sort/pagination persisted in URL search params
• Module isolation: No cross-module imports except through shared/
• API layer: All API calls through typed wrappers (never raw fetch)

Data Model Overview

The database has two scoping models:

Public Data (No Org Isolation)

Platform-wide reference data accessible to all authenticated users:

• Buildings — physical properties with address, classification, metrics
• Geography — regions, corridors, submarkets (with PostGIS boundaries)
• Lookups — size tranches, amp tranches, building parks, rail lines, NAICS codes, owner types
• Key Points — named locations (ports, airports, interchanges) for distance calculations
• Labor Data — census block group labor statistics with polygon boundaries

Org-Scoped Data (Org Isolation Enforced)

Private data belonging to a specific organization:

• Comp Leases — lease transaction records with terms, rent, tenant/owner links
• TIMs — tenant-in-market activity tracking with status workflow
• Owners — property owner entities with type classification
• Tenants — tenant entities with NAICS code classification
• Contacts — people linked to owners, tenants, or brokerage firms
• Brokerage Firms — brokerage company entities
• Broker Assignments — relationships between brokers and owners/firms
• Reports — named collections of buildings, comps, and TIMs
• Building Overrides — org-private annotations on shared buildings
• Audit Log — append-only record of all data changes
• Import Jobs — CSV import job tracking
• Error Log — API error telemetry
• API Keys — service-to-service authentication tokens

Export Schema

A separate export schema provides denormalized, BI-tool-friendly tables:

• export.export_buildings — platform-wide denormalized buildings
• export.buildings_export — org-scoped merged building + metrics + overrides
• export.export_comp_leases — org-scoped denormalized comps
• export.export_tims — org-scoped denormalized TIMs

Refresh functions rebuild export tables on demand or via scheduled jobs.

Authentication & Authorization Flow

┌──────────┐     ┌──────────┐     ┌──────────────┐     ┌──────────┐
│  User    │────▶│  Clerk   │────▶│  Frontend    │────▶│  Backend │
│ (Browser)│     │  (SSO)   │     │  (Bearer JWT)│     │  (Verify)│
└──────────┘     └──────────┘     └──────────────┘     └──────────┘
                                                              │
                                                    ┌─────────▼─────────┐
                                                    │ Extract from JWT: │
                                                    │ - user_id         │
                                                    │ - org_id          │
                                                    │ - org_permissions │
                                                    │   (scopes)        │
                                                    └───────────────────┘

1. User authenticates via Clerk (SSO/MFA)
2. Frontend obtains JWT from Clerk React SDK
3. Frontend sends Authorization: Bearer <token> on all API requests
4. Backend validates JWT signature via Clerk JWKS endpoint
5. Backend extracts user ID, org ID, and permission scopes from JWT claims
6. Backend middleware enforces required scopes per route
7. Backend repository layer filters all org-scoped data by org ID

Role Model

API Contract

• Base path: /api/v1
• Auth: Clerk JWT Bearer token (all protected routes)
• Content type: JSON request/response
• Error envelope: { code, message, details?, request_id }
• List response: { data: [], total, has_more }
• Pagination: Backend-driven via query params (page, page_size, sort, order)
• OpenAPI: Auto-generated via swaggo, drift-checked in CI

Error Codes

Release & Deployment Flow

feature branch → qa → [CI + QA validation] → PR: qa → main → production

1. Feature branches merge into qa via PR
2. CI runs: Go tests, race detection, vet, Swagger drift check, Docker compose validation
3. QA validation on staging
4. PR from qa to main requires review + green CI
5. Merge to main triggers production deploy
6. Post-deploy: verify /health, /ready, spot-check key endpoints

Hosting