bootstrap-oracle-infra

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bootstrap Oracle Infra

Everything runs locally: Docker Compose (Restate + Postgres) plus one Node
services process. Work happens in the bundled runtime at `skills/use-oracle/runtime` with sibling repos
next to it. Verify first; only bootstrap what is missing. Once prerequisites are
confirmed, proceed without check-ins; ask only on genuine ambiguity.

## Prerequisites check

```bash
docker info >/dev/null && echo docker-ok
node --version          # need 22+
restate --version       # brew install restatedev/tap/restate  (or npm i -g @restatedev/restate)
gh auth status          # PRs to Counties-trasform-scripts
```

## Scaffold `skills/use-oracle/runtime` (if missing)

Layout:

```
elephant/
  skills/use-oracle/runtime/          # your durable pipeline project (scaffolded)
    docker-compose.yml
    services/                 # TypeScript Restate services (one process)
      app.ts                  # endpoint: binds all services, listens on :9080
      county-ingest.ts        # CountyIngest workflow (feeder) + its IngestChunk child workflow
      parcel.ts               # Parcel service (prepare→transform→validate→store)
      permit-harvest.ts       # PermitHarvest service (portal harvesters per vendor)
      loader.ts               # Loader virtual object (per-county internal DB merges)
      enrichment.ts           # SunbizIngest / BbbHarvest workflows
    flows/                    # Browser Flow v2 JSON per county (elephant-cli prepare)
    transforms/               # synced from Counties-trasform-scripts (<county>/scripts/)
    docs/                     # county sources catalogs + findings
                              #   (county-discovery writes docs/<county>-sources.yaml)
    data/                     # pipeline data (gitignored): seeds/ + artifacts/
                              #   created by scaffold: mkdir -p data/seeds data/artifacts docs
  Counties-trasform-scripts/
  elephant-query-db/
  lexicon/                    # optional
```

`docker-compose.yml` (canonical):

```yaml
services:
  restate:
    image: restatedev/restate:1.7.2
    ports: ["8080:8080", "9070:9070"]
    volumes: ["restate-data:/restate-data"]
    extra_hosts: ["host.docker.internal:host-gateway"]
    environment:
      RESTATE_NODE_NAME: restate-1
    restart: unless-stopped
  postgres:
    image: postgres:16
    ports: ["5432:5432"]
    environment:
      POSTGRES_PASSWORD: elephant
      POSTGRES_DB: elephant
    volumes: ["pg-data:/var/lib/postgresql/data"]
    restart: unless-stopped
volumes:
  restate-data:
  pg-data:
```

The node name must stay stable — Restate derives it from the container hostname by
default, and a changed identity breaks restoring the persisted `restate-data` volume.

Ports: 8080 Restate ingress (invoke), 9070 Restate admin + Web UI, 9080 the services
Node process (host), 5432 Postgres.

Initialize the package so the scaffold compiles as handed off:

```bash
npm init -y
```

`tsconfig.json` (minimal):

```json
{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "target": "es2022",
    "strict": true
  }
}
```

Deps: `npm i @restatedev/restate-sdk postgres csv-parse p-limit dotenv tsx typescript
@types/node` plus
`@elephant-xyz/cli` pinned from GitHub — npm publishing has been unreliable — via
`npm i github:elephant-xyz/elephant-cli#main` (the release workflow is failing, so `main` is the source of the latest CLI; check the repo
for the latest tested tag and record the chosen ref in the project README; the npm
registry `@elephant-xyz/cli@<version>` is the fallback when publishing works), and
`npm i -D vitest`. Add `"dev": "tsx watch services/app.ts"`,
`"typecheck": "tsc --noEmit"`, and `"test": "vitest run"` to scripts.
(Playwright/Puppeteer are installed when authoring browser-based modules — permit
vendors, BBB — not part of the core scaffold.)

`.env`:

```
DATA_DIR=/absolute/path/to/elephant/skills/use-oracle/runtime/data  # absolute — sibling-repo commands rely on it
DATABASE_URL=postgresql://postgres:elephant@localhost:5432/elephant
CONCURRENCY_PREPARE=8
CONCURRENCY_TRANSFORM=16
CONCURRENCY_PERMIT_ACCELA=2
```

The `CONCURRENCY_*` caps feed in-process semaphores — see `durable-workflow-builder`
pattern 2 for how they're enforced. `DATABASE_URL` is the internal reconciliation store;
never print it. Do not configure public county pointers, catalog maps, or runtime
publishers here — Atlas publication runs later through the Elephant CLI and the Atlas
repository (`use-oracle`).

From soofi-xyz/soofi-xyz-team-kit, MIT.

More from soofi-xyz/soofi-xyz-team-kit