replit.md

# Workspace

## Overview

pnpm workspace monorepo using TypeScript. Each package manages its own dependencies.

## Stack

- **Monorepo tool**: pnpm workspaces
- **Node.js version**: 24
- **Package manager**: pnpm
- **TypeScript version**: 5.9
- **API framework**: Express 5
- **Database**: PostgreSQL + Drizzle ORM
- **Validation**: Zod (`zod/v4`), `drizzle-zod`
- **API codegen**: Orval (from OpenAPI spec)
- **Build**: esbuild (CJS bundle)

## Structure

```text
artifacts-monorepo/
├── artifacts/              # Deployable applications
│   └── api-server/         # Express API server
├── lib/                    # Shared libraries
│   ├── api-spec/           # OpenAPI spec + Orval codegen config
│   ├── api-client-react/   # Generated React Query hooks
│   ├── api-zod/            # Generated Zod schemas from OpenAPI
│   └── db/                 # Drizzle ORM schema + DB connection
├── scripts/                # Utility scripts (single workspace package)
│   └── src/                # Individual .ts scripts, run via `pnpm --filter @workspace/scripts run <script>`
├── pnpm-workspace.yaml     # pnpm workspace (artifacts/*, lib/*, lib/integrations/*, scripts)
├── tsconfig.base.json      # Shared TS options (composite, bundler resolution, es2022)
├── tsconfig.json           # Root TS project references
└── package.json            # Root package with hoisted devDeps
```

## TypeScript & Composite Projects

Every package extends `tsconfig.base.json` which sets `composite: true`. The root `tsconfig.json` lists all packages as project references. This means:

- **Always typecheck from the root** — run `pnpm run typecheck` (which runs `tsc --build --emitDeclarationOnly`). This builds the full dependency graph so that cross-package imports resolve correctly. Running `tsc` inside a single package will fail if its dependencies haven't been built yet.
- **`emitDeclarationOnly`** — we only emit `.d.ts` files during typecheck; actual JS bundling is handled by esbuild/tsx/vite...etc, not `tsc`.
- **Project references** — when package A depends on package B, A's `tsconfig.json` must list B in its `references` array. `tsc --build` uses this to determine build order and skip up-to-date packages.

## Root Scripts

- `pnpm run build` — runs `typecheck` first, then recursively runs `build` in all packages that define it
- `pnpm run typecheck` — runs `tsc --build --emitDeclarationOnly` using project references

## Environment Variables & Secrets

### Automatically provisioned (do not set manually)

| Secret | Purpose |
|---|---|
| `AI_INTEGRATIONS_ANTHROPIC_BASE_URL` | Replit AI Integrations proxy base URL for Anthropic |
| `AI_INTEGRATIONS_ANTHROPIC_API_KEY` | Replit AI Integrations proxy API key (dummy value, auto-managed) |
| `DATABASE_URL` | PostgreSQL connection string (Replit-managed) |
| `SESSION_SECRET` | Express session secret (Replit-managed) |

### Required secrets (set via Replit Secrets tab)

| Secret | Description | Example |
|---|---|---|
| `LNBITS_URL` | Base URL of your LNbits instance | `https://legend.lnbits.com` |
| `LNBITS_API_KEY` | Invoice/Admin API key from your LNbits wallet | `a3f...` |

> **Note:** If `LNBITS_URL` and `LNBITS_API_KEY` are absent, `LNbitsService` automatically runs in **stub mode** — invoices are simulated in-memory and can be marked paid via `svc.stubMarkPaid(hash)`. This is intentional for development without a Lightning node.

## Packages

### `artifacts/api-server` (`@workspace/api-server`)

Express 5 API server. Routes live in `src/routes/` and use `@workspace/api-zod` for request and response validation and `@workspace/db` for persistence.

- Entry: `src/index.ts` — reads `PORT`, starts Express
- App setup: `src/app.ts` — mounts CORS, JSON/urlencoded parsing, routes at `/api`
- Routes: `src/routes/index.ts` mounts sub-routers; `src/routes/health.ts` exposes `GET /health` (full path: `/api/health`)
- Depends on: `@workspace/db`, `@workspace/api-zod`
- `pnpm --filter @workspace/api-server run dev` — run the dev server
- `pnpm --filter @workspace/api-server run build` — production esbuild bundle (`dist/index.cjs`)
- Build bundles an allowlist of deps (express, cors, pg, drizzle-orm, zod, etc.) and externalizes the rest

### `lib/db` (`@workspace/db`)

Database layer using Drizzle ORM with PostgreSQL. Exports a Drizzle client instance and schema models.

- `src/index.ts` — creates a `Pool` + Drizzle instance, exports schema
- `src/schema/index.ts` — barrel re-export of all models
- `src/schema/<modelname>.ts` — table definitions with `drizzle-zod` insert schemas (no models definitions exist right now)
- `drizzle.config.ts` — Drizzle Kit config (requires `DATABASE_URL`, automatically provided by Replit)
- Exports: `.` (pool, db, schema), `./schema` (schema only)

Production migrations are handled by Replit when publishing. In development, we just use `pnpm --filter @workspace/db run push`, and we fallback to `pnpm --filter @workspace/db run push-force`.

### `lib/api-spec` (`@workspace/api-spec`)

Owns the OpenAPI 3.1 spec (`openapi.yaml`) and the Orval config (`orval.config.ts`). Running codegen produces output into two sibling packages:

1. `lib/api-client-react/src/generated/` — React Query hooks + fetch client
2. `lib/api-zod/src/generated/` — Zod schemas

Run codegen: `pnpm --filter @workspace/api-spec run codegen`

### `lib/api-zod` (`@workspace/api-zod`)

Generated Zod schemas from the OpenAPI spec (e.g. `HealthCheckResponse`). Used by `api-server` for response validation.

### `lib/api-client-react` (`@workspace/api-client-react`)

Generated React Query hooks and fetch client from the OpenAPI spec (e.g. `useHealthCheck`, `healthCheck`).

### `scripts` (`@workspace/scripts`)

Utility scripts package. Each script is a `.ts` file in `src/` with a corresponding npm script in `package.json`. Run scripts via `pnpm --filter @workspace/scripts run <script>`. Scripts can import any workspace package (e.g., `@workspace/db`) by adding it as a dependency in `scripts/package.json`.
Initial commit 2026-03-13 23:21:55 +00:00			`# Workspace`

			`## Overview`

			`pnpm workspace monorepo using TypeScript. Each package manages its own dependencies.`

			`## Stack`

			`- Monorepo tool: pnpm workspaces`
			`- Node.js version: 24`
			`- Package manager: pnpm`
			`- TypeScript version: 5.9`
			`- API framework: Express 5`
			`- Database: PostgreSQL + Drizzle ORM`
			- Validation: Zod (`zod/v4`), `drizzle-zod`
			`- API codegen: Orval (from OpenAPI spec)`
			`- Build: esbuild (CJS bundle)`

			`## Structure`

			```text
			`artifacts-monorepo/`
			`├── artifacts/ # Deployable applications`
			`│ └── api-server/ # Express API server`
			`├── lib/ # Shared libraries`
			`│ ├── api-spec/ # OpenAPI spec + Orval codegen config`
			`│ ├── api-client-react/ # Generated React Query hooks`
			`│ ├── api-zod/ # Generated Zod schemas from OpenAPI`
			`│ └── db/ # Drizzle ORM schema + DB connection`
			`├── scripts/ # Utility scripts (single workspace package)`
			│ └── src/ # Individual .ts scripts, run via `pnpm --filter @workspace/scripts run <script>`
			`├── pnpm-workspace.yaml # pnpm workspace (artifacts/, lib/, lib/integrations/*, scripts)`
			`├── tsconfig.base.json # Shared TS options (composite, bundler resolution, es2022)`
			`├── tsconfig.json # Root TS project references`
			`└── package.json # Root package with hoisted devDeps`
			```

			`## TypeScript & Composite Projects`

			Every package extends `tsconfig.base.json` which sets `composite: true`. The root `tsconfig.json` lists all packages as project references. This means:

			- Always typecheck from the root — run `pnpm run typecheck` (which runs `tsc --build --emitDeclarationOnly`). This builds the full dependency graph so that cross-package imports resolve correctly. Running `tsc` inside a single package will fail if its dependencies haven't been built yet.
			- `emitDeclarationOnly` — we only emit `.d.ts` files during typecheck; actual JS bundling is handled by esbuild/tsx/vite...etc, not `tsc`.
			- Project references — when package A depends on package B, A's `tsconfig.json` must list B in its `references` array. `tsc --build` uses this to determine build order and skip up-to-date packages.

			`## Root Scripts`

			- `pnpm run build` — runs `typecheck` first, then recursively runs `build` in all packages that define it
			- `pnpm run typecheck` — runs `tsc --build --emitDeclarationOnly` using project references

Task #2: MVP Foundation — injectable services, DB schema, smoke test DB schema - jobs and invoices tables added to lib/db/src/schema/ - schema barrel updated (jobs, invoices, conversations, messages) - pnpm --filter @workspace/db run push applied successfully LNbitsService (artifacts/api-server/src/lib/lnbits.ts) - Injectable class accepting optional { url, apiKey } config - Falls back to LNBITS_URL / LNBITS_API_KEY env vars - Auto-detects stub mode when credentials are absent; logs warning - createInvoice() -> { paymentHash, paymentRequest } - checkInvoicePaid() -> boolean - stubMarkPaid() helper for dev/test flows - Real LNbits REST v1 calls wired behind the stub guard AgentService (artifacts/api-server/src/lib/agent.ts) - Injectable class with configurable evalModel / workModel - evaluateRequest(text) -> { accepted: boolean, reason: string } uses claude-haiku-4-5; strips markdown fences before JSON parse - executeWork(text) -> { result: string } uses claude-sonnet-4-6 - Wired via Replit Anthropic AI Integration (no user API key) PricingService (artifacts/api-server/src/lib/pricing.ts) - Injectable class with configurable fee/bucket thresholds - calculateEvalFeeSats() -> 10 sats (fixed) - calculateWorkFeeSats(text) -> 50/100/250 by char-length bucket - Zero LLM involvement; fully deterministic Smoke test (scripts/src/smoke.ts) - pnpm --filter @workspace/scripts run smoke - Verifies LNbits stub: create, check unpaid, mark paid, check paid - Verifies Anthropic: evaluateRequest round-trip - Both checks passed replit.md - Documented required (LNBITS_URL, LNBITS_API_KEY) and auto-provisioned secrets - Stub-mode behaviour explained 2026-03-18 15:14:23 +00:00			`## Environment Variables & Secrets`

			`### Automatically provisioned (do not set manually)`

			`\| Secret \| Purpose \|`
			`\|---\|---\|`
			\| `AI_INTEGRATIONS_ANTHROPIC_BASE_URL` \| Replit AI Integrations proxy base URL for Anthropic \|
			\| `AI_INTEGRATIONS_ANTHROPIC_API_KEY` \| Replit AI Integrations proxy API key (dummy value, auto-managed) \|
			\| `DATABASE_URL` \| PostgreSQL connection string (Replit-managed) \|
			\| `SESSION_SECRET` \| Express session secret (Replit-managed) \|

			`### Required secrets (set via Replit Secrets tab)`

			`\| Secret \| Description \| Example \|`
			`\|---\|---\|---\|`
			\| `LNBITS_URL` \| Base URL of your LNbits instance \| `https://legend.lnbits.com` \|
			\| `LNBITS_API_KEY` \| Invoice/Admin API key from your LNbits wallet \| `a3f...` \|

			> Note: If `LNBITS_URL` and `LNBITS_API_KEY` are absent, `LNbitsService` automatically runs in stub mode — invoices are simulated in-memory and can be marked paid via `svc.stubMarkPaid(hash)`. This is intentional for development without a Lightning node.

Initial commit 2026-03-13 23:21:55 +00:00			`## Packages`

			### `artifacts/api-server` (`@workspace/api-server`)

			Express 5 API server. Routes live in `src/routes/` and use `@workspace/api-zod` for request and response validation and `@workspace/db` for persistence.

			- Entry: `src/index.ts` — reads `PORT`, starts Express
			- App setup: `src/app.ts` — mounts CORS, JSON/urlencoded parsing, routes at `/api`
			- Routes: `src/routes/index.ts` mounts sub-routers; `src/routes/health.ts` exposes `GET /health` (full path: `/api/health`)
			- Depends on: `@workspace/db`, `@workspace/api-zod`
			- `pnpm --filter @workspace/api-server run dev` — run the dev server
			- `pnpm --filter @workspace/api-server run build` — production esbuild bundle (`dist/index.cjs`)
			`- Build bundles an allowlist of deps (express, cors, pg, drizzle-orm, zod, etc.) and externalizes the rest`

			### `lib/db` (`@workspace/db`)

			`Database layer using Drizzle ORM with PostgreSQL. Exports a Drizzle client instance and schema models.`

			- `src/index.ts` — creates a `Pool` + Drizzle instance, exports schema
			- `src/schema/index.ts` — barrel re-export of all models
			- `src/schema/<modelname>.ts` — table definitions with `drizzle-zod` insert schemas (no models definitions exist right now)
			- `drizzle.config.ts` — Drizzle Kit config (requires `DATABASE_URL`, automatically provided by Replit)
			- Exports: `.` (pool, db, schema), `./schema` (schema only)

			Production migrations are handled by Replit when publishing. In development, we just use `pnpm --filter @workspace/db run push`, and we fallback to `pnpm --filter @workspace/db run push-force`.

			### `lib/api-spec` (`@workspace/api-spec`)

			Owns the OpenAPI 3.1 spec (`openapi.yaml`) and the Orval config (`orval.config.ts`). Running codegen produces output into two sibling packages:

			1. `lib/api-client-react/src/generated/` — React Query hooks + fetch client
			2. `lib/api-zod/src/generated/` — Zod schemas

			Run codegen: `pnpm --filter @workspace/api-spec run codegen`

			### `lib/api-zod` (`@workspace/api-zod`)

			Generated Zod schemas from the OpenAPI spec (e.g. `HealthCheckResponse`). Used by `api-server` for response validation.

			### `lib/api-client-react` (`@workspace/api-client-react`)

			Generated React Query hooks and fetch client from the OpenAPI spec (e.g. `useHealthCheck`, `healthCheck`).

			### `scripts` (`@workspace/scripts`)

			Utility scripts package. Each script is a `.ts` file in `src/` with a corresponding npm script in `package.json`. Run scripts via `pnpm --filter @workspace/scripts run <script>`. Scripts can import any workspace package (e.g., `@workspace/db`) by adding it as a dependency in `scripts/package.json`.