Getting Started & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Poneglyph is a high-performance humanitarian intelligence platform designed to visualize and analyze global survey datasets. It leverages a monorepo architecture to provide a unified development experience across its frontend web application, backend API, and shared internal packages. Sources: README.md:1-15
The project is built on a modern stack emphasizing type safety and speed, utilizing Bun as the primary runtime and Turborepo for orchestration. The primary objective of the setup process is to establish a local environment capable of running a Next.js frontend and a Hono-based backend while maintaining a connection to a PostgreSQL database managed via Drizzle ORM. Sources: README.md:3-15, package.json:52-54
Environment Prerequisites
Before initiating the setup, ensure the following software is installed on your local machine:
- Bun: The project's primary package manager and runtime environment. Sources: README.md:11, package.json:54
- PostgreSQL: The required database engine for data storage. Sources: README.md:13
- Node.js/NPM: While Bun is preferred, some dependencies may require standard Node toolchains. Sources: apps/web/package.json:44
Tech Stack Overview
| Category | Technology |
|---|---|
| Runtime | Bun |
| Monorepo Tool | Turborepo |
| Frontend Framework | Next.js (React 19) |
| Backend Framework | Hono |
| ORM | Drizzle ORM |
| Styling | TailwindCSS 4 |
| Authentication | Better-Auth |
Sources: README.md:3-15, package.json:1-20, apps/web/package.json:1-30
Project Architecture
Poneglyph utilizes a monorepo structure managed by Turborepo. This allows for shared configuration and code reuse across different applications. Sources: README.md:15, package.json:4-10
The diagram above illustrates the workspace relationships within the Poneglyph repository. Sources: README.md:58-66, package.json:4-10
Installation & Initial Setup
To set up the project locally, follow these steps in order:
1. Dependency Installation
Clone the repository and run the installation command from the root directory using Bun.
bun install
Sources: README.md:19-21
2. Database Configuration
Poneglyph requires a PostgreSQL database.
- Establish a PostgreSQL instance locally or in the cloud.
- Navigate to
apps/server/and locate or create the.envfile. - Add your
DATABASE_URLand other required environment variables.
Sources: README.md:27-31
3. Schema Propagation
Push the database schema defined in the @Poneglyph/db package to your live PostgreSQL instance:
bun run db:push
Sources: README.md:35-37, package.json:34
Development Workflow
Once the environment is configured, you can start the development servers. Sources: README.md:39-44
Running the Applications
| Command | Action |
|---|---|
bun run dev | Starts both the web and server applications simultaneously via Turbo. |
bun run dev:web | Starts only the Next.js frontend on http://localhost:3001. |
bun run dev:server | Starts only the Hono backend on http://localhost:3000. |
Sources: README.md:41-44, package.json:28-32
Code Quality and Linting
The project uses Oxlint and Oxfmt for fast linting and formatting. To verify code quality, run:
bun run check
Sources: README.md:53-55, package.json:38
Shared UI Customization
The project uses a shared UI package located in packages/ui. This package contains shadcn/ui primitives used by the web application. Sources: README.md:46-51
- Global Styles: Modify
packages/ui/src/styles/globals.css. - Shared Components: Located in
packages/ui/src/components/*. - Adding Components: Use the shadcn CLI targeting the UI package:
npx shadcn@latest add [component] -c packages/ui
Sources: README.md:47-52, packages/ui/package.json:4-10
Summary
Setting up Poneglyph involves configuring a Bun-based monorepo, establishing a PostgreSQL database, and utilizing Turborepo to manage the interplay between the Next.js frontend and Hono backend. By following the standard installation and database push commands, developers can quickly achieve a functional environment for humanitarian data analysis. Sources: README.md:1-70, package.json:27-40