Infrastructure Planning

Infrastructure Planning Skill

This skill helps plan and document all the infrastructure, external services, and logistics a Paperclip company needs to operate.

When to Use

• Setting up infrastructure for a new company
• Auditing what services an existing company needs
• Planning CI/CD, deployment, and hosting
• Documenting infrastructure decisions

Infrastructure Categories

1. Source Code & Version Control

GitHub is the default. Each company needs:

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

2. Container Registry

Docker Hub is the default:

3. Orchestration & Hosting

Kubernetes is the default:

Namespace plan:

4. Domain & DNS

5. Communication

Slack (recommended):

6. Productivity

Google Workspace (recommended):

Agent access via gws CLI:

• gws CLI is pre-installed in the Paperclip container
• GWS skills (gmail, drive, calendar, sheets, etc.) are pre-installed globally at /paperclip/.codex/skills/gws-* — all agents can use them
• Each company needs a GWS service account JSON key (see the GWS setup guide)
• Place the key at .company/gws/<company-slug>.json in the Paperclip repo root
• It is mounted into the container at /paperclip/.gws/<company-slug>.json
• Agents that need GWS access set GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/paperclip/.gws/<company-slug>.json via .paperclip.yaml env inputs / adapter env

7. Payments

Stripe (recommended for prepaid/subscription models):

8. Database

PostgreSQL (recommended):

9. Logistics (Physical Products)

If the company ships physical products:

10. Monitoring & Observability

Deployment Flow Template

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/CD Pipeline (GitHub Actions)

ci.yml — runs on PRs:

• Checkout code
• Install dependencies
• Run tests (pytest, npm test)
• Lint and type-check

deploy.yml — runs on merge to main:

• Build Docker images
• Push to Docker Hub with commit SHA and latest tags
• (Optional) Deploy to dev namespace

Environment Variables per Environment

Infrastructure → Environment Variables Mapping

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.

Only include env vars for infrastructure the company actually uses. For example, a company without Stripe integration does not need STRIPE_SECRET_KEY.

Infrastructure Document Template

When generating infrastructure.md for a company, include:

1. Source Code — GitHub org, repo URL, monorepo layout
2. Container Registry — Docker Hub account, image naming convention
3. Kubernetes — cluster info, namespace plan, services
4. Database — engine, per-environment setup
5. Payments — provider, env vars needed
6. Paperclip Container Access — tools available inside the container

Paperclip Container Tools

Agents run inside the Paperclip Docker container and have access to: