Architecture
Poliage uses a monorepo architecture that separates concerns while maintaining a unified development experience.
Repository Structure
poliage/
├── cli/ # CLI Tool (pnpm workspace)
│ └── poliage-cli/
│ ├── src/ # CLI source code
│ └── web/ # Embedded web interface
├── src/ # Main Next.js Application
│ ├── app/ # App Router pages
│ ├── components/ # React components
│ ├── lib/ # Utilities and helpers
│ └── middleware/ # Auth and routing middleware
├── prisma/ # Database schema
└── docs/ # This documentation siteSystem Components
CLI Tool (cli/poliage-cli)
The CLI is the primary interface for capturing documentation. It's built with:
Commander.js
Command-line argument parsing and subcommand routing
Puppeteer
Headless browser automation for screenshot capture
Express
Embedded web server for interactive capture mode
Key capabilities:
- Headless capture: Automated screenshot capture from CLI
- Interactive mode: Web-based capture interface
- Configuration-driven: JSON config files define capture behavior
Main Application (src/)
The core platform is a Next.js 14+ application providing:
Database Schema
Core entities in the Prisma schema:
model User {
id String @id
email String @unique
projects Project[]
}
model Project {
id String @id
slug String @unique
ownerId String
owner User @relation(fields: [ownerId], references: [id])
commits VisualCommit[]
}
model VisualCommit {
id String @id
projectId String
project Project @relation(fields: [projectId], references: [id])
assets Asset[]
createdAt DateTime @default(now())
}
model Asset {
id String @id
commitId String
commit VisualCommit @relation(fields: [commitId], references: [id])
path String
url String
}Data Flow
Capture Phase
The CLI launches a headless browser, navigates to specified URLs, and captures screenshots based on configuration.
Processing Phase
Captured images are optimized (compressed, resized) locally before upload.
Sync Phase
Assets are uploaded to cloud storage, and metadata is saved to the database as a new VisualCommit.
Rendering Phase
The hosted documentation site reads from the latest VisualCommit to display current assets.
Authentication Flow
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Browser │───────▶ │ Clerk │───────▶ │ Poliage │
│ (User) │◀─────── │ (Auth) │◀─────── │ (API) │
└─────────────┘ Token └──────────────┘ Verify └─────────────┘CLI authentication uses API tokens generated in the dashboard. See CLI Reference for details.
Deployment Architecture
Production Environment
Multi-Tenant Hosting
Each project gets a unique subdomain:
https://{project-slug}.poliage.comThe platform uses a wildcard DNS configuration with middleware-based routing to serve the correct project content.