Monorepo System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Poneglyph utilizes a high-performance monorepo architecture managed by Turborepo and the Bun runtime environment. This structure is designed to facilitate the development of humanitarian intelligence tools, including a data-driven web application and an AI-powered research server. By leveraging workspaces, the project shares critical logic, UI components, and database schemas across different applications to ensure consistency and type safety.
Sources: README.md:1-25, package.json:1-15
Workspace Organization
The repository is divided into two primary directories: apps/ for deployable services and packages/ for shared internal libraries. This separation allows for independent deployment while maintaining a shared codebase for core logic.
| Category | Path | Description |
|---|---|---|
| Apps | apps/web | Frontend application built with Next.js and TailwindCSS. |
| Apps | apps/server | Backend API server powered by Hono and Bun. |
| Packages | packages/ui | Shared UI component library using shadcn/ui and Tailwind. |
| Packages | packages/db | Database management, Drizzle ORM schemas, and migrations. |
| Packages | packages/auth | Shared authentication configuration and logic. |
| Packages | packages/schemas | Zod-based validation schemas shared across the stack. |
Sources: README.md:65-71, package.json:5-15, packages/schemas/package.json:3-9
Component Relationship Diagram
The following diagram illustrates how the shared packages are consumed by the primary applications.
Build and Execution System
The project employs Turborepo to orchestrate tasks across the monorepo, providing optimized caching and parallel execution for development, building, and database management.
Global Scripts and Tooling
Scripts defined in the root package.json allow for cross-workspace execution.
bun run dev: Starts all applications (web and server) in development mode.bun run build: Executes the build pipeline for all workspaces.bun run check: Runs Oxlint and Oxfmt for project-wide linting and formatting.- Database Operations: Prefixed with
db:, these scripts (push, generate, migrate) target the@Poneglyph/dbworkspace.
Sources: package.json:28-40, README.md:73-85
Data Persistence and Schema Management
The architecture uses a centralized database package (packages/db) to manage a PostgreSQL database via Drizzle ORM. This package is the source of truth for the application's data model.
Database Schema Structure
The system tracks humanitarian datasets, user accounts, and research logs.
Shared Validation
The @Poneglyph/schemas package exports Zod objects to ensure that data conforms to the database model at every layer (API request, internal processing, and UI form entry).
./chat: Validations for research agent interactions../dataset: Schemas for dataset metadata../upload: Constraints for file upload processes.
Sources: packages/schemas/package.json:3-9
Application Layer Overview
Web Application (apps/web)
A Next.js frontend that utilizes the shared @Poneglyph/ui package for interface consistency. It handles user interactions, dataset exploration, and visual storytelling.
- Framework: Next.js 16.2.3
- Styling: TailwindCSS with
packages/uiprimitives. - State: React 19 with TanStack Form for data entry.
Sources: apps/web/package.json:20-29, README.md:43-50
Server (apps/server)
A lightweight Hono-based API server that integrates AI agents for deep research and internal database searching.
- Runtime: Bun
- AI Integration: Utilizes
@ai-sdk/google,@ai-sdk/groq, and@tavily/ai-sdk. - Storage: AWS SDK for S3 management and Upstash Redis for caching.
Sources: apps/server/package.json:17-30, apps/server/src/agents/prompts/system.ts:5-15
Conclusion
The Poneglyph architecture is a modern, type-safe monorepo that prioritizes developer velocity and system reliability. By centralizing UI components and database schemas, the system ensures that the frontend and backend remain perfectly synchronized, while Turborepo provides the necessary performance optimizations for scaling humanitarian data analysis.