Introduction to Poneglyph
Relevant source files
The following files were used as context for generating this wiki page:
Poneglyph is a comprehensive humanitarian intelligence platform designed to empower NGO workers, researchers, and journalists with actionable insights derived from both internal humanitarian datasets and the broader web. The system functions as an AI-powered research assistant, bridging the gap between raw data collection and strategic decision-making in high-stakes environments.
Sources: apps/server/src/agents/prompts/system.ts:1-7, apps/web/src/app/dashboard/page.tsx:135-138
The project is structured as a modern monorepo utilizing TypeScript across the full stack. It integrates high-performance components including a Next.js frontend, a Hono backend server, and a specialized AI agent orchestration layer to handle complex research queries and data visualizations.
Sources: README.md:3-14, package.json:2-10
System Architecture
Poneglyph employs a monorepo structure managed by Turborepo, separating concerns into applications (apps/) and shared modules (packages/).
Project Structure
| Module | Description |
|---|---|
apps/web | Frontend application built with Next.js and TailwindCSS. |
apps/server | Backend API and AI agent logic built with Hono. |
packages/ui | Shared UI primitives and design tokens based on shadcn/ui. |
packages/db | Database schema and Drizzle ORM queries. |
packages/auth | Authentication logic powered by Better-Auth. |
Sources: README.md:58-65, package.json:4-15
Technology Stack
The architecture is built on the Bun runtime and leverages PostgreSQL for data persistence through the Drizzle ORM.
- Frontend: Next.js (React 19), TailwindCSS, GSAP for animations.
- Backend: Hono server framework.
- Database: PostgreSQL with Drizzle ORM.
- AI/ML: Gemini-based web search and Tavily-powered multi-step deep research.
Sources: README.md:3-14, apps/web/package.json:15-32, apps/server/src/agents/prompts/system.ts:15-25
AI Research Intelligence
The core of Poneglyph is the Research Assistant, which utilizes specialized prompts and tools to process humanitarian queries. It operates via an orchestrator that selects the most appropriate research tool based on user needs.
Agent Capabilities
The system provides three primary tools for intelligence gathering:
- Internal Database Search (
searchDatabase): Interfaces with the curated repository of field reports and NGO-uploaded datasets. - Web Search (
webSearch): Provides real-time grounding via Google Search through Gemini. - Deep Research (
deepResearch): Executes multi-step investigations using Tavily for complex synthesis and fact-checking.
Sources: apps/server/src/agents/prompts/system.ts:9-25, apps/server/src/agents/prompts/deep-research.ts:1-12
Research Workflow
The following diagram illustrates how the AI assistant processes a research request:
The assistant is instructed to prefer parallel execution of database and web searches to ensure comprehensive results while maintaining a professional and analytical tone.
Sources: apps/server/src/agents/prompts/system.ts:33-43, apps/server/src/agents/prompts/deep-research.ts:3-12
Data Ecosystem
Poneglyph facilitates an "open dataset hub" where users can explore, analyze, and contribute data.
Dataset Management
The platform supports several data file types including CSV, JSON, JSONL, and Parquet. Metadata for these datasets includes titles, descriptions, summaries, publishers, and tags.
Sources: apps/web/src/app/datasets/upload/page.tsx:288-290, apps/web/src/app/datasets/upload/page.tsx:244-275
Key Data Features
- Visual Stories: AI-powered analysis transforms survey data into visualized articles and dashboards.
- Dataset Upload: A multi-step contribution pipeline allowing volunteers to submit data and build reputation.
- Research Dashboard: An interactive interface for exploring files, conducting searches, and viewing real-time research status logs.
Sources: apps/web/src/app/dashboard/page.tsx:135-138, apps/web/src/app/datasets/upload/page.tsx:143-157, apps/web/src/app/research/page.tsx:14-38
Dataset Model
| Field | Type | Description |
|---|---|---|
title | String | The official name of the dataset. |
description | Text | Detailed information on content and utility. |
publisher | String | The entity providing the data (e.g., NGO, NOAA). |
tags | Array | Categorical tags (e.g., climate, health). |
fileTypes | Array | Supported formats (CSV, JSON, etc.). |
Sources: apps/web/src/app/dashboard/[id]/page.tsx:190-201, apps/web/src/app/datasets/upload/page.tsx:244-275
User Interface & Experience
The frontend is designed for clarity and rapid insight extraction, utilizing a clean, professional aesthetic.
Component Structure
- Dashboard: Features a carousel of "Daily Data" stories and a filterable grid of global research articles.
- Research Interface: A specialized view with a conversation thread, status logs for agent activity, and interactive media placeholders.
- Navigation: A sticky header providing access to Insights, Research, Datasets, and the Upload portal.
Sources: apps/web/src/app/dashboard/page.tsx:142-200, apps/web/src/app/research/page.tsx:14-55, apps/web/src/components/navigation.tsx:32-60
Interaction Flow
Conclusion
Poneglyph serves as a specialized humanitarian intelligence node. By combining a modern TypeScript monorepo architecture with specialized AI agents and a community-driven dataset hub, it provides a centralized platform for processing complex global crises data into actionable insights for the humanitarian sector.