Skip to main content

🏗️ Architecture Overview

Three Separate Services​

Open Navigator consists of three distinct services that work together:

┌─────────────────────────────────────────────────────────┐
│                 Open Navigator Platform                  │
├─────────────────────────────────────────────────────────┤
│                                                           │
│  📚 Documentation Site (Docusaurus)                      │
│  └─> http://localhost:3000                              │
│      • Project overview and marketing                    │
│      • API documentation and guides                      │
│      • Installation instructions                         │
│      • Links to dashboard                                │
│                                                           │
│  ⚛️  Interactive Dashboard (React + Vite)               │
│  └─> http://localhost:5173                              │
│      • Real-time data visualization                      │
│      • Search and filter capabilities                    │
│      • Interactive heatmap                               │
│      • Document explorer                                 │
│      • Nonprofit search                                  │
│      • Opportunity tracker                               │
│                                                           │
│  🔥 API Backend (FastAPI + Python)                       │
│  └─> http://localhost:8000                              │
│      • Data ingestion and processing                     │
│      • Multi-agent AI system                             │
│      • Database connections                              │
│      • API endpoints for dashboard                       │
│                                                           │
└─────────────────────────────────────────────────────────┘

Why Three Services?​

📚 Documentation Site (website/)​

  • Purpose: Documentation, guides, and project information
  • Technology: Docusaurus (static site generator)
  • Port: 3000
  • Use Case: First-time visitors, documentation, API reference

⚛️ Dashboard (frontend/)​

  • Purpose: Interactive data exploration and analysis
  • Technology: React 18 + TypeScript + Vite
  • Port: 5173
  • Use Case: Daily users exploring data, creating reports, searching

🔥 API Backend (api/)​

  • Purpose: Data processing and AI agents
  • Technology: FastAPI + Python
  • Port: 8000
  • Use Case: Powers the dashboard, runs background jobs

Integration Points​

Documentation → Dashboard​

  • Navbar has "🚀 Dashboard" link pointing to http://localhost:5173
  • Homepage has "Launch Dashboard" button
  • /dashboard page auto-redirects to React app

Dashboard → API​

  • All data requests go to http://localhost:8000/api/*
  • Real-time updates via API polling
  • Authentication handled via API

API → Dashboard​

  • Serves static built dashboard in production
  • Provides REST endpoints for all data

Development Workflow​

./start-all.sh

This launches all three services in tmux:

  • Window 0: API Backend
  • Window 1: React Dashboard
  • Window 2: Documentation Site
  • Window 3: Shell

Option 2: Start Individually​

# Terminal 1: API
source .venv/bin/activate
python main.py serve

# Terminal 2: Dashboard
cd frontend
npm run dev

# Terminal 3: Documentation
cd website
npm start

Access Points​

ServiceDevelopment URLPurpose
Documentationhttp://localhost:3000Read guides and API docs
Dashboardhttp://localhost:5173Main application interface
APIhttp://localhost:8000Backend services
API Docshttp://localhost:8000/docsInteractive API reference

User Journey​

  1. Discovery: User visits documentation site (port 3000)
  2. Getting Started: Reads installation guides
  3. Launch: Clicks "Dashboard" → Opens React app (port 5173)
  4. Usage: Interacts with dashboard, which calls API (port 8000)

Production Deployment​

In production, the architecture changes:

┌─────────────────────────────────────────────────────────┐
│              Production Deployment                        │
├─────────────────────────────────────────────────────────┤
│                                                           │
│  🌐 Reverse Proxy (nginx/Databricks Apps)               │
│  └─> https://opennavigator.org                          │
│                                                           │
│      ├─ /              → Docusaurus static build         │
│      ├─ /docs          → Docusaurus static build         │
│      ├─ /dashboard     → React static build              │
│      └─ /api/*         → FastAPI backend                 │
│                                                           │
└─────────────────────────────────────────────────────────┘

Build Commands​

# Build documentation
cd website && npm run build
# Output: website/build/

# Build dashboard
cd frontend && npm run build
# Output: frontend/dist/

# Deploy backend
# FastAPI serves both static builds

Key Files​

Documentation Site​

  • website/docusaurus.config.ts - Configuration
  • website/src/pages/index.tsx - Homepage
  • website/docs/ - Documentation markdown files

Dashboard​

  • frontend/src/App.tsx - Main routes
  • frontend/src/pages/Dashboard.tsx - Homepage with stats
  • frontend/src/pages/Heatmap.tsx - Interactive map
  • frontend/src/pages/Documents.tsx - Search interface
  • frontend/src/pages/Nonprofits.tsx - Nonprofit search
  • frontend/src/pages/Opportunities.tsx - Opportunity tracker

API​

  • api/app.py - Databricks Apps entry point
  • api/main.py - Standalone mode
  • agents/ - Multi-agent system
  • discovery/ - Data ingestion

Common Confusion​

❌ Wrong: "The documentation site IS the application" ✅ Correct: "The documentation site LINKS TO the application"

❌ Wrong: "Port 3000 has search and filters" ✅ Correct: "Port 5173 (React dashboard) has search and filters"

❌ Wrong: "Docusaurus replaced the dashboard" ✅ Correct: "Docusaurus was added FOR documentation, dashboard is unchanged"

Troubleshooting​

"I can't find the search feature"​

→ You're on the documentation site. Click "🚀 Dashboard" in the navbar to access the React app.

→ Make sure React dev server is running (cd frontend && npm run dev)

"No data showing in dashboard"​

→ Make sure API backend is running (python main.py serve)

"Everything looks different"​

→ Documentation site (port 3000) is new. Dashboard (port 5173) is unchanged.

Next Steps​