# W7S PaaS Developer Guide (`w7s.io/agents.md`)

Status: active  
Owner: platform  
Last reviewed: 2026-03-25

W7S is a repo-scoped PaaS for backend developers and AI engineers.
You deploy code from GitHub, get runtime endpoints per org/repo, and integrate auth/plugins without running your own auth gateway.

## 1) Platform URL Model

- Runtime app (your deployed APIs/webhooks):
  - `https://<org>.w7s.cloud/<repo>/<path>`
- Deploy endpoints:
  - `POST https://<org>.w7s.cloud/_deploy`
  - `POST https://<org>.w7s.cloud/<repo>/_deploy`
- Account/auth service:
  - Runtime-proxied org scope: `https://<org>.w7s.cloud/_account/*`
  - Runtime-proxied: `https://<org>.w7s.cloud/<repo>/_account/*`
  - Direct: `https://account.w7s.io/*`
- Dashboard/plugin config:
  - `https://dashboard.w7s.io/<org>?view=plugin`
  - `https://dashboard.w7s.io/<org>/<repo>?view=plugin`

## 2) Request + Deploy Flow

1. Push your backend repo to GitHub.
2. Build and upload an archive in CI.
3. Call W7S deploy endpoint with auth + git metadata headers.
4. Runtime stores the snapshot and route metadata.
5. Requests to `/<repo>/<path>` execute your handlers.

### Required deploy headers

- `Authorization: Bearer <token>`
- `x-github-repository: <owner>/<repo>`
- `x-github-sha: <commit-sha>`
- `x-github-branch: <branch>`

### Example deploy call

```bash
curl -X POST "https://<org>.w7s.cloud/<repo>/_deploy" \
  -H "Authorization: Bearer $W7S_TOKEN" \
  -H "x-github-repository: <org>/<repo>" \
  -H "x-github-sha: <sha>" \
  -H "x-github-branch: main" \
  -F "archive=@dist.zip"
```

## 3) Fastest Google Login (via `/_account`)

This is the recommended developer path because it keeps auth org/repo scoped.

### Start login from your app

```ts
const org = "acme";
const repo = "my-api";
const redirectUrl = window.location.href;

const authUrl = new URL(`https://${org}.w7s.cloud/${repo}/_account/google/auth`);
authUrl.searchParams.set("redirect_url", redirectUrl);
window.location.assign(authUrl.toString());
```

What happens:

1. Runtime proxies `/<repo>/_account/google/auth` to account service.
2. Account runs Google OAuth.
3. On success, account sets the session cookie and redirects back to your `redirect_url`.
4. Your app can then call `/<repo>/_account/verify` (or `/<repo>/_account/session`) to read the authenticated user.

### Verify session from frontend or backend

```bash
curl "https://<org>.w7s.cloud/<repo>/_account/verify" \
  -H "Cookie: session_token=<token>"
```

### Useful auth endpoints

- Login: `GET /<repo>/_account/google/auth`
- Native Google exchange: `POST /<repo>/_account/google/native/exchange`
- Verify session: `GET /<repo>/_account/verify` (alias: `/<repo>/_account/session`)
- Logout: `GET /<repo>/_account/logout?redirect_url=<url>`
- OIDC metadata: `GET /<repo>/_account/.well-known/openid-configuration`
- JWKS: `GET /<repo>/_account/.well-known/jwks.json`

For native/mobile clients:

```bash
curl "https://<org>.w7s.cloud/<repo>/_account/google/native/exchange" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"idToken":"<google-id-token>","clientId":"<google-web-client-id>"}'
```

## 4) Direct Account Domain (Alternative)

If you are integrating without org-host proxying, use direct scoped endpoints:

- `https://account.w7s.io/google/auth/<org>/<repo>?redirect_url=<url>`

Callback behavior depends on which Google OAuth client account service resolves for the request:

- Repo-scoped or org-scoped Google client configured:
  - Start auth on `https://<org>.w7s.cloud/<repo>/_account/google/auth?redirect_url=<url>`
  - Google `redirect_uri` is `https://<org>.w7s.cloud/<repo>/_account/google/callback`
- Shared default env Google client fallback:
  - Start auth may still begin from `https://<org>.w7s.cloud/<repo>/_account/google/auth?redirect_url=<url>` or `https://account.w7s.io/google/auth/<org>/<repo>?redirect_url=<url>`
  - Google `redirect_uri` is the single direct account callback `https://account.w7s.io/callback`
  - Scoped org/repo context and the final app redirect are carried in OAuth `state`

For Google Cloud Console callback registration, use the callback URI emitted by account service for your environment. `https://account.w7s.io/debug-oauth` helps confirm active OAuth config.

## 5) JWT/OIDC Contract

- Account issues RS256 JWTs.
- Consumers verify against account JWKS.
- Typical claims used by downstream services: `sub`, `email`, `iss`, scoped context.
- Runtime, editor-api, and telemetry all verify against account JWKS.

## 6) Plugin and Integration Model

- Runtime exposes plugin methods through the runtime bridge.
- Org/repo plugin vars/secrets are managed from dashboard.
- Effective config precedence is repo -> org -> defaults.
- Runtime can resolve missing runtime plugin config from account internal endpoint.

## 7) npm SDK Quick Start (`@w7s-io/sdk`)

Install:

```bash
npm install @w7s-io/sdk drizzle-orm
```

Set env for local scripts:

```bash
export W7S_ORG_URL="https://<org>.w7s.cloud"
export W7S_REPO="<org>/<repo>"
export GITHUB_TOKEN="<github-token>"
```

Note: some older example docs use `W7S_WORKSPACE_URL`; current SDK config uses `W7S_ORG_URL`.

Minimal SDK call:

```ts
import w7s, { createW7SClient } from "@w7s-io/sdk";

const text = await w7s.agent("Say hello in one line");

const client = createW7SClient({
  orgUrl: process.env.W7S_ORG_URL,
  repo: process.env.W7S_REPO,
  token: process.env.GITHUB_TOKEN,
});

const result = await client.plugin("openai.responses.create", {
  model: "gpt-5-mini",
  input: "hello",
});
```

## 8) Databases, Creation, and Migration Paths

W7S database scope is:

- `org + repo + databaseName`

Migration discovery in deploy archives is path-based:

- `db/<databaseName>/migrations/*.sql`
- If your deploy root is `backend/`, this becomes `backend/db/<databaseName>/migrations/*.sql`.

Important behavior:

- Deploy auto-runs migrations before webhook provisioning.
- There is no separate manual "create database" step in normal flow; the DB is materialized when migration/status/query/execute runs for that scope.
- If migrations fail, deploy fails.

## 9) Drizzle Pattern

Define schema:

- `db/schema.ts` or `backend/db/schema.ts`

Use a shared DB client module:

```ts
import { createW7SDbClient } from "@w7s-io/sdk";
import * as schema from "./schema";

export const drizzleDb = createW7SDbClient({
  repo: "<org>/<repo>",
  databaseName: "app", // or "logging", etc.
  schema,
});
```

Optional migration generation with Drizzle Kit:

```ts
// drizzle.config.ts
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "sqlite",
  schema: "./db/schema.ts",
  out: "./db/app/migrations",
});
```

For runtime handlers, keep SQL/Drizzle logic in query modules (for example `backend/queries/*`) and call those from handlers.

## 10) Real Repo Examples

- `../w7s-hello-world`
  - schema: `db/schema.ts`
  - migrations: `db/app/migrations/*.sql`
  - drizzle config: `drizzle.config.ts` (`out: ./db/app/migrations`)
  - runtime usage: `src/db.ts`, `src/db-ro.ts` with `createW7SDbClient(...)`
- `../58arepas`
  - schema: `backend/db/schema.ts`
  - migrations: `backend/db/app/migrations/*.sql`
  - DB scope: `backend/db/scope.ts`
  - shared client: `backend/db/client.ts`
  - handlers call query layer: `backend/queries/*`
- `../58arepas-logging`
  - DB scope sets database to `logging` in `backend/db/scope.ts`
  - shared client: `backend/db/client.ts`
  - migrations currently in `backend/db/app/migrations/*.sql`
  - for strict path-to-database matching, use `backend/db/logging/migrations/*.sql`

## 11) Minimum Integration Checklist

1. Configure Google OAuth credentials in account scope:
   - global env fallback: `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`
   - org/repo plugin config overrides: `google.ACCOUNT_OAUTH_CLIENT_ID`, `google.ACCOUNT_OAUTH_CLIENT_SECRET`
   - optional default post-login redirect override: `google.DEFAULT_REDIRECT_URI`
2. Use `https://<org>.w7s.cloud/<repo>/_account/google/auth?redirect_url=...` in your app.
3. After redirect, call `/<repo>/_account/verify` and store user state.
4. For backend calls, pass cookie or Bearer token and verify JWT.
5. For service-to-service Google scopes, use account OAuth broker endpoints (`/oauth/*`).

## 12) Canonical Technical References

- Service map: `https://w7s.io/agents.md` (this file)
- Internal docs source:
  - `docs/services/overview.md`
  - `docs/services/account/integration.md`
  - `docs/operations/deploy.md`
  - `docs/plugins/catalog.md`
  - `docs/repo/services/account/AGENTS.md`