infrastructure/Agents.md

# Agent System Reference

Quick reference for AI agents working in Will's infrastructure. Read this before doing any infrastructure work.

---

## Machines

| Machine | Role |
|---------|------|
| Local Mac | Dev workstation (primary) |

Legion is gone. All production services now run on GCP.

---

## Production Environment — GCP

All production services run on Google Cloud Platform, project `neuron-785695`.

| Service | URL | Platform |
|---------|-----|----------|
| Marketing site | https://neurontechnologies.ai | Cloud Run (3 regions) |
| Accounts | https://accounts.neurontechnologies.ai | Cloud Run (3 regions) |
| REST API | https://api.neurontechnologies.ai | Cloud Run (3 regions) |
| Soma (AI inference gateway) | https://ai.neurontechnologies.ai | Cloud Run (us-central1) |

### Artifact Registry

Images are pushed to `us-central1-docker.pkg.dev/neuron-785695/`:

| Service | Registry path |
|---------|---------------|
| Marketing | `neuron-marketing/marketing` |
| Accounts | `neuron-accounts/accounts` |
| API | `neuron-api/api` |
| Soma | `neuron-soma/soma` |

### GCP CLI

```bash
gcloud auth login
gcloud config set project neuron-785695
gcloud auth configure-docker us-central1-docker.pkg.dev --quiet
```

---

## Secrets — GCP Secret Manager

**GCP Secret Manager is the source of truth for all production secrets.**

### Access via gcloud CLI

```bash
gcloud secrets versions access latest --secret=<secret-name>
```

### Secrets in use

| Secret name | Purpose |
|-------------|---------|
| `jwt-secret` | JWT signing key (accounts, api) |
| `license-admin-token` | License admin token (api) |
| `accounts-database-url` | Cloud SQL connection string (accounts) |
| `soma-hf-token` | HuggingFace API token (soma) |
| `soma-operator-key` | Soma operator/service key (soma) |
| `stripe-secret-key` | Stripe API key |
| `stripe-webhook-secret` | Stripe webhook signing secret |
| `stripe-price-professional` | Stripe Professional plan price ID |
| `stripe-price-founding` | Stripe Founding Member price ID |

### How secrets flow to Cloud Run

Secrets are injected as environment variables via Secret Manager references in Terraform Cloud Run service definitions. No ESO, no Vault.

```
GCP Secret Manager → Terraform secret_key_ref → Cloud Run env var → pod env
```

---

## Infrastructure Management

### The split: Terraform vs Cloud Run

| Layer | Tool | What it owns |
|-------|------|-------------|
| Infrastructure | **Terraform** | Cloud Run services, Artifact Registry, Secret Manager secrets, Load balancer, SSL certs, Cloudflare DNS, Cloud SQL, IAM |
| Secrets | **Secret Manager** | All production secrets — referenced in Terraform, never hardcoded |

**Never deploy Cloud Run changes with `gcloud run deploy` directly.** All changes go through Terraform.

### Running Terraform (GCP)

```bash
cd ~/Development/infrastructure/servers/gcp/
# direnv auto-loads credentials if configured, or:
export GOOGLE_APPLICATION_CREDENTIALS=~/.config/gcloud/application_default_credentials.json
terraform plan
terraform apply
```

State is stored in Cloudflare R2 bucket `legion-terraform-state` (key: `gcp/terraform.tfstate`).

### Repo layout

```
~/Development/
  infrastructure/                      ← this repo
    AGENTS.md                          ← you are here
    servers/
      gcp/
        *.tf                           ← Terraform (all GCP infra)
  neuron-technologies/
    soma/                              ← Soma AI inference gateway (Rust)
    neuron-rest/                       ← REST API (Go)
    accounts/                          ← Accounts service (Go)
    marketing/                         ← Marketing site (Next.js)
```

---

## CI/CD

### Gitea Actions (neuralplatform.ai was on Legion — now gone)

Gitea is gone with Legion. Use GitHub Actions for CI/CD.

- Workflows: `.github/workflows/`
- Push images to GCP Artifact Registry from CI using the `neuron-ci-pusher` service account
- CI SA key stored as `GCP_SA_KEY` repo secret (JSON key from `neuron-ci-pusher@neuron-785695.iam.gserviceaccount.com`)

### Docker push pattern

```bash
gcloud auth configure-docker us-central1-docker.pkg.dev --quiet
docker buildx build --platform linux/amd64 \
  -t us-central1-docker.pkg.dev/neuron-785695/<repo>/<service>:latest \
  --push .
```

---

## Services & Domains

| Domain | Backend | Notes |
|--------|---------|-------|
| neurontechnologies.ai | GCP LB → Cloud Run | Marketing site, 3 regions |
| www.neurontechnologies.ai | GCP LB → Cloud Run | Marketing site alias |
| api.neurontechnologies.ai | GCP LB → Cloud Run | REST API, 3 regions |
| accounts.neurontechnologies.ai | GCP LB → Cloud Run | Accounts service, 3 regions |
| ai.neurontechnologies.ai | GCP LB → Cloud Run | Soma inference gateway, us-central1 |

All domains share one global anycast IP (`marketing-ip-prod`). DNS A records in Cloudflare point to that IP.

---

## Load Balancer

- Global external HTTPS load balancer (`marketing-urlmap-prod`)
- Single IP (`google_compute_global_address.prod`)
- Host-based routing via URL map
- SSL certs: Google-managed, auto-renewed
- Cloud Armor: SQLi/XSS protection + rate limiting (1000 req/min per IP)
- CDN enabled for marketing site only

---

## Terraform Cloudflare DNS

Cloudflare DNS A records for `neurontechnologies.ai` subdomains are managed in the GCP Terraform (`servers/gcp/`). The Cloudflare provider is configured via environment variable `CLOUDFLARE_API_TOKEN`.

Zone ID for `neurontechnologies.ai`: `e844374f203dca4944d77d40ca0710ae`

---

## Key Paths

| What | Where |
|------|-------|
| This repo | `~/Development/infrastructure/` |
| GCP Terraform | `~/Development/infrastructure/servers/gcp/` |
| Soma (inference gateway) | `~/Development/neuron-technologies/soma/` |
| GCP credentials | `~/.config/gcloud/` |
| Secrets/tokens | `~/Secrets/` |

---

## What NOT To Do

- `gcloud run deploy` directly — use Terraform
- Hardcode any secret value — store in GCP Secret Manager
- Commit `terraform.tfstate` — state is in R2, never local
- Add `kubernetes_*` resources to Terraform — there is no k8s cluster anymore