Architecture
Technical architecture of the Postbase platform.
System Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ POSTBASE PLATFORM │
├─────────────────────────────────┬───────────────────────────────────────────┤
│ LOCAL DEVELOPMENT │ CLOUD PLATFORM │
│ │ │
│ ┌─────────────────────────┐ │ ┌─────────────────────────────────────┐│
│ │ @postbase/cli │ │ │ @postbase/cloud ││
│ │ • Database commands │ │ │ Cloudflare Worker at Edge ││
│ │ • Migration engine │ │ │ ││
│ │ • Type generation │───┼──▶│ • GitHub OAuth ││
│ │ • Cloud operations │ │ │ • Project management ││
│ └───────────┬─────────────┘ │ │ • Database provisioning ││
│ │ │ │ • Backup orchestration ││
│ ┌───────────▼─────────────┐ │ └──────────────┬──────────────────────┘│
│ │ @postbase/daemon │ │ │ │
│ │ Hono API on :9432 │ │ ┌──────────────▼──────────────────────┐│
│ │ │ │ │ Infrastructure ││
│ │ • Docker management │ │ │ ││
│ │ • PostgreSQL control │ │ │ ┌────────────┐ ┌────────────────┐ ││
│ │ • Migration execution │ │ │ │ Railway │ │ Cloudflare │ ││
│ │ • Query proxy │ │ │ │ PostgreSQL │ │ D1 + R2 + KV │ ││
│ └───────────┬─────────────┘ │ │ └────────────┘ └────────────────┘ ││
│ │ │ │ ││
│ ┌───────────▼─────────────┐ │ │ ┌────────────────────────────────┐ ││
│ │ PostgreSQL │ │ │ │ @postbase/backup-service │ ││
│ │ Docker Container │ │ │ │ Railway Docker Container │ ││
│ │ │ │ │ │ │ ││
│ │ • supabase/postgres │ │ │ │ • pg_dump / pg_restore │ ││
│ │ • Multiple databases │ │ │ │ • pg_receivewal (PITR) │ ││
│ │ • Pre-installed exts │ │ │ │ • R2 streaming upload │ ││
│ └─────────────────────────┘ │ │ └────────────────────────────────┘ ││
│ │ └─────────────────────────────────────┘│
│ ┌─────────────────────────┐ │ │
│ │ @postbase/ui │ │ │
│ │ React Admin Panel │ │ │
│ │ │ │ │
│ │ • Schema browser │ │ │
│ │ • Data viewer/editor │ │ │
│ │ • SQL editor │ │ │
│ │ • Migration manager │ │ │
│ └─────────────────────────┘ │ │
└─────────────────────────────────┴───────────────────────────────────────────┘Package Structure
postbase/
├── packages/
│ ├── cli/ # Command-line interface
│ ├── daemon/ # Local API server
│ ├── cloud/ # Cloudflare Worker API
│ ├── backup-service/ # Backup Docker container
│ ├── postgres-image/ # Custom PostgreSQL image
│ ├── sdk/ # TypeScript client SDK
│ ├── shared/ # Shared types and schemas
│ ├── ui/ # React admin interface
│ ├── cdn/ # Static asset hosting
│ └── docs/ # Documentation (Vocs)
├── docs/ # Architecture documents
└── package.json # pnpm monorepo rootTechnology Stack
Frontend
| Package | Technologies |
|---|---|
@postbase/ui | React 18, Vite, TanStack Query/Table, Monaco Editor, shadcn/ui, Tailwind CSS |
@postbase/docs | Vocs, MDX, React |
Backend
| Package | Technologies |
|---|---|
@postbase/daemon | Hono, TypeScript, tsx, dockerode, pg |
@postbase/cloud | Hono, Cloudflare Workers, D1, KV, R2 |
@postbase/backup-service | Hono, Docker, pg_dump, pg_receivewal, AWS SDK |
CLI & SDK
| Package | Technologies |
|---|---|
@postbase/cli | Commander.js, chalk, ora, pg, tsx |
@postbase/sdk | Kysely, pg, TypeScript |
@postbase/shared | Zod, TypeScript |
Data Flow
Local Development
┌──────────┐ HTTP ┌──────────┐ postgres ┌────────────┐
│ CLI │──────────────▶│ Daemon │───────────────▶│ PostgreSQL │
│ │ │ :9432 │ │ :5432 │
└──────────┘ └──────────┘ └────────────┘
│
┌──────────┐ HTTP │
│ UI │────────────────────┘
│ :3000 │
└──────────┘Cloud Platform
┌──────────┐ HTTPS ┌──────────┐ Railway ┌────────────┐
│ CLI │──────────────▶│ Cloud │──────API─────▶│ PostgreSQL │
│ │ │ API │ │ Railway │
└──────────┘ └──────────┘ └────────────┘
│
D1 / KV / R2
│
┌──────────▼──────────┐
│ Backup Service │
│ (Railway) │
└─────────────────────┘Backup Flow
┌────────────────┐
│ Cloud API │
│ (Cloudflare) │
└───────┬────────┘
│
POST /backup
│
┌───────▼────────┐
│ Backup Service │
│ (Railway) │
└───────┬────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───────▼───────┐ │ ┌───────▼───────┐
│ PostgreSQL │──pg_dump──────│ R2 │
│ (Railway) │ │ (Cloudflare) │
└───────────────┘ └───────────────┘
│
callback
│
┌───────▼────────┐
│ Cloud API │
│ Update D1 meta │
└────────────────┘PITR Flow
Continuous
┌───────────────────┐ WAL Streaming
│ PostgreSQL │──────pg_receivewal────────────┐
│ (Railway) │ │
└───────────────────┘ │
┌───────▼───────┐
│Backup Service │
└───────┬───────┘
│
Upload WAL
│
┌───────▼───────┐
│ R2 │
│ WAL Storage │
└───────────────┘
Recovery:
┌──────────┐ ┌───────────────┐
│ Cloud API│──POST /pitr-restore│Backup Service │
└──────────┘ └───────┬───────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───────▼───────┐ │ ┌───────▼───────┐
│ R2 │───download────│ temp restore │
│ base + WAL │ │ folder │
└───────────────┘ └───────┬───────┘
│
pg_restore +
WAL replay
│
┌───────▼───────┐
│ PostgreSQL │
└───────────────┘Cloud Services
Cloudflare
| Service | Purpose |
|---|---|
| Workers | Cloud API at api.postbase.sh |
| D1 | Relational metadata (users, projects, databases, backups) |
| KV | Session storage, device codes |
| R2 | Backup storage, WAL archives |
Railway
| Service | Purpose |
|---|---|
| PostgreSQL | Cloud database instances |
| Docker | Backup service container |
GitHub
| Feature | Purpose |
|---|---|
| OAuth | User authentication |
| Container Registry | Custom PostgreSQL images |
Security
Authentication
- Local: No authentication (trusted local environment)
- Cloud: GitHub OAuth with device flow
- Backup Service: Shared secret token
Data Protection
- Passwords: 32-character cryptographically random
- Backups: Encrypted at rest in R2
- Transit: HTTPS for all cloud communication
- Credentials: Stored in
~/.postbase/, never in version control
Network
- Railway: Private networking, SSL optional
- Cloudflare: Edge TLS termination
- Backup Service: Internal Railway network
Scalability
Current Limits
| Resource | Limit |
|---|---|
| Databases per project | 10 |
| Backup size | 10 GB |
| WAL retention | 7 days |
| API rate limit | 60 req/min (free) |
Future Scaling
- Read Replicas: Railway regional deployment
- Connection Pooling: PgBouncer integration
- Multi-region: Edge routing with Cloudflare
- High Availability: Primary-replica failover