Plan and document the required software, infrastructure, and logistics for a Paperclip company — domains, GitHub, Docker Hub, Kubernetes, Slack, Google Workspace, Stripe, shipping providers, and CI/CD pipelines. Use when setting up infrastructure for a new company or auditing what an existing company needs.
This skill helps plan and document all the infrastructure, external services, and logistics a Paperclip company needs to operate.
GitHub is the default. Each company needs:
| Resource | Description |
|---|---|
| GitHub Organization | Company org for all repositories |
| Monorepo | Single repository for all services, apps, and infra |
| GitHub CLI () |
ghAuthenticated in Paperclip container via GH_TOKEN |
| GitHub Actions | CI/CD workflows for testing and deployment |
Monorepo layout (recommended):
{company-name}/
apps/
web/ # Frontend (React/TypeScript or Next.js)
Dockerfile
package.json
src/
services/
api/ # Backend API (FastAPI or Express)
Dockerfile
pyproject.toml
src/
{domain-service}/ # Domain-specific services
Dockerfile
src/
packages/
shared/ # Shared types, utilities, constants
infra/
helm/ # Helm charts for each service
k8s/ # Raw K8s manifests (alternative to Helm)
docker-compose.yml # Local dev stack
.github/
workflows/
ci.yml # Test on PR
deploy.yml # Build + push + deploy on merge
README.md
Docker Hub is the default:
| Resource | Description |
|---|---|
| Docker Hub account | Push/pull container images |
| Image naming | {account}/{company}-{service}:{tag} |
| Tags | latest, v{semver}, sha-{commit}, dev |
| Auth | DOCKER_HUB_USERNAME + DOCKER_HUB_TOKEN in Paperclip container |
Kubernetes is the default:
| Resource | Description |
|---|---|
| Cluster | microk8s-local (dev) or cloud (GKE, EKS, AKS) |
| Namespaces | {company}-dev, {company}-staging, {company}-prod |
| Ingress | Traefik as reverse proxy |
| Helm | Chart templating for each service |
| Tools | kubectl, helm installed in Paperclip container |
Namespace plan:
| Namespace | Purpose |
|---|---|
{company}-dev | Development and testing |
{company}-staging | Pre-production validation |
{company}-prod | Production |
| Resource | Description |
|---|---|
| Primary domain | {company}.{tld} (e.g., .cz, .com, .io) |
| DNS provider | Cloudflare, Route53, or registrar DNS |
| SSL/TLS | Let's Encrypt via cert-manager or Traefik |
Slack (recommended):
| Channel | Purpose |
|---|---|
#general | Company-wide announcements |
#engineering | Technical discussions |
#marketing | Marketing and content |
#operations | Ops, fulfillment, logistics |
#alerts | Automated alerts from monitoring |
Google Workspace (recommended):
| Service | Use |
|---|---|
| Gmail | Company email ({name}@{domain}) |
| Calendar | Meeting scheduling, deadlines |
| Drive | Document storage and collaboration |
| Docs/Sheets | Business documents, spreadsheets |
Agent access via gws CLI:
gws CLI is pre-installed in the Paperclip container/paperclip/.codex/skills/gws-* — all agents can use them.company/gws/<company-slug>.json in the Paperclip repo root/paperclip/.gws/<company-slug>.jsonGOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/paperclip/.gws/<company-slug>.json in their runtime/settings.json envStripe (recommended for prepaid/subscription models):
| Resource | Description |
|---|---|
| Stripe account | Payment processing |
| Test mode | sk_test_..., pk_test_... for dev/staging |
| Live mode | sk_live_..., pk_live_... for production |
| Webhooks | STRIPE_WEBHOOK_SECRET for event handling |
| Payment methods | Cards, Apple Pay, Google Pay, SEPA, iDEAL, Bancontact |
PostgreSQL (recommended):
| Environment | Setup |
|---|---|
| Dev | docker-compose or microk8s StatefulSet |
| Staging | Same as dev or managed |
| Production | Managed (Cloud SQL, RDS) or self-hosted StatefulSet |
If the company ships physical products:
| Region | Provider | Notes |
|---|---|---|
| Czech Republic | Zasilkovna (Packeta) | Pickup points + home delivery |
| EU | DHL, DPD, GLS | Standard parcel |
| International | DHL Express, FedEx, UPS | Priority/express |
| Packaging | Custom branded boxes | Design via CMO/ContentCreator |
| Tool | Purpose |
|---|---|
| Grafana | Dashboards and alerting |
| Prometheus | Metrics collection |
| Loki | Log aggregation |
| Sentry | Error tracking (frontend + backend) |
Agent writes code
-> git push to GitHub
-> Unit tests run locally (pytest / npm test)
-> docker build (inside Paperclip container)
-> docker push to Docker Hub
-> helm upgrade / kubectl apply to K8s
-> Verify via API/browser
ci.yml — runs on PRs:
deploy.yml — runs on merge to main:
latest tags| Category | Dev | Staging | Prod |
|---|---|---|---|
| Database | Local PG | Staging PG | Prod PG (managed) |
| Payments | Test keys | Test keys | Live keys |
| AI/ML APIs | Test keys | Test keys | Prod keys |
| Domain | localhost | staging.{domain} | {domain} |
Each infrastructure category requires specific environment variables to be configured as company secrets in Paperclip. Use this mapping when generating scripts/setup-secrets.sh for a company.
| Infrastructure Category | Env Var | Kind | Description |
|---|---|---|---|
| Source Code (GitHub) | GH_TOKEN | secret | GitHub personal access token for gh CLI |
| Container Registry (Docker Hub) | DOCKER_HUB_USERNAME | secret | Docker Hub username |
| Container Registry (Docker Hub) | DOCKER_HUB_TOKEN | secret | Docker Hub access token |
| Payments (Stripe) | STRIPE_SECRET_KEY | secret | Stripe secret API key |
| Payments (Stripe) | STRIPE_WEBHOOK_SECRET | secret | Stripe webhook signing secret |
| Database (PostgreSQL) | DATABASE_URL | secret | PostgreSQL connection string |
| AI Media (Gemini) | GEMINI_API_KEY | secret | Google Gemini API key |
| AI Media (ElevenLabs) | ELEVENLABS_API_KEY | secret | ElevenLabs TTS API key |
| Media Output | MEDIA_OUTPUT_DIR | plain | Output directory for generated media |
| Monitoring (Sentry) | SENTRY_DSN | plain | Sentry error tracking DSN |
| Communication (Slack) | SLACK_WEBHOOK_URL | plain | Slack webhook for automated notifications |
| Productivity (Google Workspace) | GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE | plain | Path to GWS service account JSON for gws CLI (e.g. /paperclip/.gws/<company>.json) |
Only include env vars for infrastructure the company actually uses. For example, a company without Stripe integration does not need STRIPE_SECRET_KEY.
When generating infrastructure.md for a company, include:
Agents run inside the Paperclip Docker container and have access to:
| Tool | Purpose |
|---|---|
codex | Codex CLI |
gh | GitHub CLI (authenticated via GH_TOKEN) |
docker | Docker CLI (host daemon via mounted socket) |
kubectl | Kubernetes CLI (host kubeconfig mounted) |
helm | Helm chart manager |
git | Version control |
python3 | Python runtime |
uv | Python package manager |
node | Node.js runtime |
npm | Node.js package manager |
gws | Google Workspace CLI (Gmail, Calendar, Drive, Sheets, Docs) |