Frontend
Next.js 15 App Router application with React 19, MapLibre GL maps, TanStack Query, Zustand state management, and Clerk authentication for the TerraGuard dashboard.
Overview
The tg-frontend is the web application that humanitarian teams interact with daily. Built with Next.js 15 (App Router) and React 19, it provides a real-time disaster event dashboard with interactive maps, event filtering, AI-powered summaries, knowledge base management, report editing, and team administration.
The application runs on port 4000 and communicates with the Backend API for all data operations.
Architecture
Key Features
Interactive Map Dashboard
The main view renders disaster events on a MapLibre GL map with:
- Color-coded markers by alert level (Red, Orange, Green)
- Event type icons (earthquake, cyclone, flood, etc.)
- Click-to-view event details
- Geographic filtering and bounding box search
Responsive Design
The application adapts to desktop and mobile viewports with a responsive layout:
- Desktop: Side-by-side map and event list panels
- Mobile: Stacked layout with collapsible panels
Authentication
Clerk handles authentication with Google sign-in support. The middleware (src/middleware.ts) protects all routes except the sign-in page. Multi-tenant organization support allows users to belong to different teams with role-based access.
State Management
The application uses a dual state management approach:
| Layer | Technology | Purpose |
|---|---|---|
| Server State | TanStack Query (React Query) | API data fetching, caching, and synchronization |
| Client State | Zustand | UI state, filters, selections, form data |
Over 20 Zustand stores manage different domains of UI state, from event filters to chat history to knowledge base interactions.
Rich Text Editing
The TipTap editor powers report editing with:
- Rich formatting (headings, lists, tables)
- AI-generated content insertion
- Template-based report sections
- Export to multiple formats
Data Validation
All API request and response types are validated with Zod schemas (src/zod-schemas/), providing runtime type safety and consistent error handling.
Configuration
The frontend is configured via environment variables in .env.local:
| Variable | Description | Default |
|---|---|---|
NEXT_PUBLIC_API_URL | Backend API base URL | http://localhost:5601/api/v1 |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Clerk publishable key | required |
CLERK_SECRET_KEY | Clerk secret key (server-side) | required |
NEXT_PUBLIC_CLERK_SIGN_IN_URL | Sign-in page path | /sign-in |
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL | Post-sign-in redirect | / |
NEXT_PUBLIC_MAPLIBRE_STYLE_URL | MapLibre GL style URL | required |
Key Views
| View | Route | Description |
|---|---|---|
Home | / | Main dashboard with map and event list |
EventView | /events | Event list with advanced filtering |
EventDetailsView | /events/[id] | Single event detail with news, knowledge, AI chat |
KnowledgeView | /knowledge | Knowledge base browser and search |
AlertStreamView | /alert-stream | Alert stream configuration |
OrganizationSettings | /settings | Organization, teams, matrices |
ReportTemplateView | /report-templates | Report template management |
VFCountriesView | /countries | Country configuration |
Directory Structure
tg-frontend/
├── src/
│ ├── app/
│ │ ├── layout.tsx # Root layout with providers
│ │ ├── middleware.ts # Clerk auth middleware
│ │ ├── globals.css # Global styles
│ │ ├── (auth)/ # Auth routes (sign-in, sign-up)
│ │ ├── (root)/ # Authenticated app routes
│ │ ├── (embed)/ # Embeddable views
│ │ └── alert-stream/ # Alert stream routes
│ ├── views/
│ │ ├── Home.tsx # Dashboard main view
│ │ ├── EventView.tsx # Event list
│ │ ├── EventDetailsView.tsx # Event detail
│ │ ├── KnowledgeView.tsx # Knowledge base
│ │ ├── AlertStreamView.tsx # Alert stream
│ │ └── OrganizationSettings.tsx
│ ├── components/ # Shared React components
│ │ ├── ui/ # Radix UI primitives
│ │ ├── map/ # MapLibre GL components
│ │ ├── charts/ # Recharts components
│ │ └── editor/ # TipTap editor components
│ ├── services/
│ │ ├── event.service.ts # Event API calls
│ │ ├── auth.service.ts # Auth API calls
│ │ ├── team.service.ts # Team management
│ │ └── ...
│ ├── stores/
│ │ ├── event-table.store.ts
│ │ ├── knowledge.store.ts
│ │ ├── chat.store.ts
│ │ ├── organizations.store.ts
│ │ └── ... (20+ stores)
│ ├── hooks/ # Custom React hooks
│ ├── types/ # TypeScript type definitions
│ ├── utils/ # Utility functions
│ ├── helpers/ # Helper functions
│ ├── contexts/ # React contexts
│ ├── providers/ # Provider wrappers (Query, Clerk)
│ ├── lib/ # Library configuration
│ ├── data/ # Static data and constants
│ └── zod-schemas/ # Zod validation schemas
├── public/ # Static assets
├── next.config.js
├── tailwind.config.ts
├── tsconfig.json
└── package.jsonRunning
# Install dependencies
npm install
# Start development server (Turbopack)
npm run dev
# Production build
npm run build
# Run linter
npm run lintTechnology Stack
| Technology | Version | Purpose |
|---|---|---|
| Next.js | 15 | React framework with App Router |
| React | 19 | UI library |
| TypeScript | 5.x | Type safety |
| Clerk | latest | Authentication and user management |
| TanStack Query | v5 | Server state management |
| Zustand | latest | Client state management |
| Radix UI | latest | Accessible UI primitives |
| MapLibre GL | latest | Interactive map rendering |
| TipTap | latest | Rich text editor |
| Recharts | latest | Data visualization charts |
| Zod | latest | Schema validation |
| Tailwind CSS | v4 | Utility-first CSS |
Web Crawler
Go API server with Python crawl4ai worker featuring a 4-level strategy fallback chain for reliable web content extraction from news sites and official reports.
GeoPop API
Rust-based reverse geocoding and population analysis service providing exposure assessments, land/sea detection, and country lookups for disaster events.