Web Application Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Poneglyph web application is a full-stack React environment built using the Next.js framework. It serves as the primary interface for an AI-powered humanitarian intelligence platform, allowing users to browse open datasets, view data-driven stories, and contribute new information. The architecture is designed as part of a monorepo that separates the frontend (Next.js), backend (Hono), and shared packages (UI, Auth, Database).
Sources: README.md:3-30, apps/web/src/app/layout.tsx:32-45
Core Technologies and Frameworks
The web application leverages a modern TypeScript stack optimized for performance and type safety. Key technologies include:
- Next.js: The core React framework for routing and rendering.
- TailwindCSS: Used for utility-first styling across all components.
- Bun: The primary runtime environment and package manager.
- Turborepo: Manages the monorepo structure and build pipeline.
- Shadcn/UI: A collection of shared UI primitives located in a dedicated package.
Sources: README.md:3-15, apps/web/package.json:10-40
Monorepo Structure
The project utilizes a monorepo approach to share logic and styles between the web application and the server.
The diagram above illustrates how the web application consumes shared logic and UI components from the packages/ directory.
Sources: README.md:95-101, apps/web/package.json:11-13
Frontend Application Routing
The web application uses the Next.js App Router. The structure is organized into specific functional areas:
Landing and Discovery
The root page provides a high-level overview of the platform, including "How it Works" and "Community Pillars" sections. It uses GSAP for complex hero animations.
Sources: apps/web/src/app/page.tsx:7-140
Dashboard and Insights
The dashboard serves as a hub for data stories (Articles). It includes a carousel for featured content and a filtered grid for categorized topics such as Health, Climate, and Economics.
Sources: apps/web/src/app/dashboard/page.tsx:80-260
Dataset Management
Users can contribute to the ecosystem via a dedicated upload interface. This module handles multi-file uploads (CSV, JSON, Parquet) and provides real-time previews of how the dataset will appear to the community.
Sources: apps/web/src/app/datasets/upload/page.tsx:120-430
Component Architecture
The UI is built using a combination of shared primitives and app-specific blocks.
| Component Type | Location | Purpose |
|---|---|---|
| Shared Primitives | packages/ui/src/components | Reusable UI elements like Buttons, Inputs, and Badges using shadcn/ui. |
| Navigation | apps/web/src/components/navigation.tsx | Sticky global header with mobile-responsive toggles. |
| Domain Logic | apps/web/src/app/dashboard/components | Specialized components like ArticleCard for data visualization. |
| Agent Interface | apps/web/src/components/research/ | AI agent panels for interactive research and chat. |
Sources: README.md:50-70, apps/web/src/components/navigation.tsx:30-110, apps/web/src/app/dashboard/[id]/page.tsx:250-400
Data Flow and API Integration
The web application communicates with the backend API (running on Hono) using a typed client.
This flow shows the typical request cycle for fetching humanitarian data displayed in the UI.
Sources: apps/web/src/app/dashboard/[id]/page.tsx:195-215, apps/server/package.json:20-30
Configuration and Styling
The application uses a centralized styling configuration. Global styles and design tokens are defined in packages/ui, which are then consumed by the Next.js layout.tsx.
- Fonts: The app utilizes several Google Fonts including Geist, Newsreader, and JetBrains Mono for a distinct technical yet readable aesthetic.
- Theme:
next-themesis used for managing light/dark modes. - Environment: Workspace-local environment variables are managed via
@Poneglyph/env.
Sources: apps/web/src/app/layout.tsx:1-40, apps/web/package.json:28-30
Summary
The Poneglyph Web Application Architecture is a modular, TypeScript-heavy implementation of Next.js. By leveraging a monorepo structure, it ensures consistency between the frontend interface and the AI-driven backend services while maintaining a highly responsive, animated UI for humanitarian intelligence analysts.