Project Overview & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
Polar is an open-source payment infrastructure and monetization platform designed specifically for developers and SaaS businesses. It operates as a Merchant of Record (MoR), which means it assumes the liability for international sales taxes (VAT, GST) and handles global compliance, billing, and receipts on behalf of its users. This allows developers to sell digital products, subscriptions, and GitHub repository access with minimal administrative overhead.
The project is managed as a monorepo containing a Python/FastAPI backend and a TypeScript-based frontend ecosystem including Next.js web dashboards and mobile applications. The architecture is designed for high reliability, utilizing a modular backend structure, asynchronous task processing via workers, and a shared UI component library.
Sources: README.md:26-34, CLAUDE.md:1-5, DEVELOPMENT.md:104-108
System Architecture
Polar's stack is composed of a decoupled frontend and backend that communicate via a REST API. The infrastructure relies on specialized storage and processing units to handle real-time payments and background automation.
High-Level Component Flow
The following diagram illustrates the relationship between the web client, the internal API, and external integrations like Stripe.
The architecture separates long-running tasks into workers and uses Redis as the communication bus.
Sources: DEVELOPMENT.md:1-24, AGENTS.md:17-30
Core Technologies
| Component | Technology | Description |
|---|---|---|
| Backend | Python / FastAPI | High-performance REST API. |
| Frontend | Next.js / React | Dashboard and landing pages using TanStack Query. |
| Primary Database | PostgreSQL | Relational storage for users, orgs, and products. |
| Cache & Queue | Redis | Powering Dramatiq tasks and caching layers. |
| Task Worker | Dramatiq | Asynchronous background job processing. |
| ORM | SQLAlchemy | Database abstraction layer for Python. |
| Storage | MinIO / S3 | Storage for digital downloads and assets. |
Sources: CLAUDE.md:65-75, AGENTS.md:17-30, DEVELOPMENT.md:1-8
Local Development Setup
Polar provides a specialized CLI tool called dev to automate the orchestration of its multi-service environment.
Prerequisites & Initialization
The quickest way to start is using the internal dev tool which handles dependency checks and environment generation.
- Install CLI tool:
./dev/cli/install(One-time setup). - Launch Environment:
dev up- This installs Homebrew, Docker, uv, pnpm, and Node.js if missing. It also starts the infrastructure containers. - Seed Data:
dev seed --new-org <org-name>to create initial test data.
Sources: DEVELOPMENT.md:26-40, CLAUDE.md:46-48
Manual Configuration
If not using the automated dev tool, developers must manually configure the environment files:
# Generate .env files
./dev/setup-environment
# For GitHub integration
./dev/setup-environment --setup-github-app --backend-external-url https://yourdomain.ngrok.dev
Sources: CLAUDE.md:46-52, DEVELOPMENT.md:42-48
Service Execution
Once the environment is configured, services must be run in parallel terminals:
| Command | Service | URL/Access |
|---|---|---|
dev api (or uv run task api) | Backend API | http://127.0.0.1:8000 |
dev worker (or uv run task worker) | Background Jobs | Process logs |
dev web (or pnpm dev) | Frontend Dashboard | http://127.0.0.1:3000 |
uv run task db_migrate | Alembic Migrations | Database schema updates |
Sources: CLAUDE.md:7-14, DEVELOPMENT.md:38-40, AGENTS.md:34-40
External Integrations Setup
To fully test Polar's capabilities locally, specific integrations with GitHub and Stripe are required.
Stripe Integration
Stripe is used for processing payments. For local development, it requires specific environment variables and a webhook listener.
- API Keys: Add
POLAR_STRIPE_SECRET_KEYandPOLAR_STRIPE_PUBLISHABLE_KEYtoserver/.env. - Webhook Listener: Use
dev stripeto forward events. - Secrets: Signing secrets
POLAR_STRIPE_WEBHOOK_SECRETandPOLAR_STRIPE_CONNECT_WEBHOOK_SECRETmust be set for the server to validate incoming events.
Sources: DEVELOPMENT.md:71-102, CLAUDE.md:54-59
GitHub Integration
Used for authentication and repository-based benefits.
- The script
./dev/setup-environment --setup-github-appassists in creating a temporary GitHub App. - It requires an external URL (e.g., via
ngrok) to route webhooks to the local development environment.
Sources: DEVELOPMENT.md:49-60, CLAUDE.md:50-52
Docker-Based Development
Polar supports an alternative, fully containerized setup for isolated environments or consistent developer experiences across machines.
The Docker setup supports multiple instances (Instance 0, 1, 2) on incremented port ranges.
Sources: DEVELOPMENT.md:143-186
Common Docker Commands
- Start Detached:
dev docker up -d - Shell Access:
dev docker shell api - Multiple Instances:
dev docker up -i 1 -d(Runs API on 8100 and Web on 3100). - Monitoring:
dev docker up --monitoring(Includes Prometheus and Grafana).
Sources: DEVELOPMENT.md:162-186
Summary
Polar provides a robust monetization platform with a modern architecture that prioritizes developer ergonomics. Local setup is streamlined through the dev CLI tool, allowing developers to choose between native execution using uv and pnpm or a fully isolated Docker-based environment. Successful contribution requires setting up local environment variables and configuring external webhooks for Stripe and GitHub to simulate real-world Merchant of Record operations.