Deployment Guide & Strategy
Relevant source files
The following files were used as context for generating this wiki page:
Poneglyph utilizes a modern monorepo architecture managed by Turborepo and Bun, designed for scalable cloud-native deployment. The system is split into a Next.js frontend, a Hono-based API server, and specialized Rust/Axum workers for intensive data tasks.
The infrastructure is provisioned via Terraform on Google Cloud Platform (GCP), specifically leveraging Cloud Run for serverless execution. This strategy ensures high availability and automatic scaling for humanitarian intelligence analysis.
Sources: README.md:1-20, terraform/README.md:1-5, package.json:1-15
Core Infrastructure & Services
The Poneglyph ecosystem is deployed as a set of decoupled services on Google Cloud Run. This approach allows the API and workers to scale independently based on demand.
| Service | Technology | Role | Access Level |
|---|---|---|---|
poneglyph-server | Next.js / Hono | Main API & Frontend | Public |
poneglyph-upload-worker | Rust / Axum | Upload processing | Internal (Pub/Sub) |
PostgreSQL | Drizzle ORM | Primary Database | Private |
S3 Bucket | AWS/GCP compatible | File Storage | Private |
Sources: terraform/README.md:7-15, apps/server/package.json:20-25, README.md:5-15
Deployment Architecture
The following diagram illustrates the high-level deployment flow and resource relationships on GCP.
The architecture uses Pub/Sub as an asynchronous bridge between the API server and background workers to ensure heavy upload tasks do not block the main user interface.
Sources: terraform/README.md:17-25, terraform/variables.tf:10-25
Build & Environment Configuration
Poneglyph employs a centralized build system using Turborepo to manage dependencies across the workspace.
Available Build Scripts
The project uses bun as the primary runtime and package manager.
bun run build: Executesturbo buildto compile all applications and packages.bun run check: Performs linting using Oxlint and formatting via Oxfmt.bun run db:push: Synchronizes the Drizzle schema with the remote PostgreSQL instance.
Sources: package.json:25-35, README.md:65-75
Critical Environment Variables
The deployment requires specific secrets and configuration parameters defined in the Terraform stack.
| Variable | Description | Source |
|---|---|---|
DATABASE_URL | Connection string for PostgreSQL | terraform/variables.tf:76 |
BETTER_AUTH_SECRET | Secret key for Better-Auth | terraform/variables.tf:81 |
S3_ENDPOINT | URL for the object storage service | terraform/variables.tf:95 |
GOOGLE_GENERATIVE_AI_API_KEY | API key for Gemini/AI features | terraform/variables.tf:104 |
TAVILY_API_KEY | Key for deep research tool searches | terraform/variables.tf:114 |
Continuous Integration & Deployment (CI/CD)
The deployment strategy leverages containerization. Terraform variables define the specific images to be pulled for both the server and worker services.
Service Configuration Details
API Server (apps/server)
The server runs on Bun and uses the Hono framework. It is configured for a max_scale of 2 instances by default to manage costs while providing redundancy. It serves as the coordinator for AI agents (Gemini/Groq) and handles authentication via better-auth.
Sources: apps/server/package.json:5-15, terraform/variables.tf:33-35
Upload Worker (apps/workers/upload-worker)
Implemented in Rust for performance, this worker is internal-only. It is triggered exclusively via Pub/Sub push subscriptions. When a file is uploaded to the S3 bucket, a notification is sent to the worker to initiate processing and embedding.
Sources: terraform/README.md:18-25, terraform/variables.tf:57-65
Conclusion
The Poneglyph deployment strategy prioritizes a serverless, event-driven architecture. By utilizing Terraform for Infrastructure-as-Code and Google Cloud Run for compute, the project ensures that the humanitarian intelligence platform remains cost-effective, scalable, and resilient.