@podosoft/podokit 1.0.2 → 1.1.4

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.module.ts

@@ -1,4 +1,4 @@
-import type { RedisClient } from "bun";
+import { CACHE, type CacheStore } from "@podosoft/podokit-runtime";
 import { AppException } from "../common/app-exception";
 import { API_KEY_VERIFIER } from "../api-key/api-key.module";
 import {
@@ -7,7 +7,6 @@ import {
   type RequestGuardContext,
   type ServiceKey,
 } from "../core/services";
-import { REDIS } from "../redis/redis.module";
 import { rateLimitConfig, type RateLimitConfig } from "./rate-limit.config";
 import { RateLimitIdentity } from "./rate-limit.identity";
 
@@ -20,39 +19,18 @@ export interface RateLimitStorage {
   increment(key: string, ttlSeconds: number): Promise<RateLimitIncrement>;
 }
 
-const INCREMENT_SCRIPT = `
-local count = redis.call('INCR', KEYS[1])
-if count == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end
-local ttl = redis.call('TTL', KEYS[1])
-return { count, ttl }
-`;
-
-function resultNumber(value: unknown): number | undefined {
-  if (typeof value === "number") return value;
-  if (typeof value === "string") {
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? parsed : undefined;
-  }
-  return undefined;
-}
-
-export class RedisRateLimitStorage implements RateLimitStorage {
-  constructor(private readonly client: RedisClient) {}
+export class CacheRateLimitStorage implements RateLimitStorage {
+  constructor(private readonly cache: CacheStore) {}
 
   async increment(key: string, ttlSeconds: number): Promise<RateLimitIncrement> {
-    const result = await this.client.send("EVAL", [
-      INCREMENT_SCRIPT,
-      "1",
-      key,
-      String(ttlSeconds),
-    ]);
-    if (!Array.isArray(result)) throw new Error("Redis returned an invalid rate-limit result");
-    const count = resultNumber(result[0]);
-    const retryAfterSeconds = resultNumber(result[1]);
-    if (count === undefined || retryAfterSeconds === undefined) {
-      throw new Error("Redis returned an invalid rate-limit counter");
-    }
-    return { count, retryAfterSeconds: Math.max(1, retryAfterSeconds) };
+    const result = await this.cache.incrementFixedWindow(key, {
+      windowMs: ttlSeconds * 1_000,
+      limit: Number.MAX_SAFE_INTEGER,
+    });
+    return {
+      count: result.count,
+      retryAfterSeconds: Math.max(1, Math.ceil((result.resetAt - Date.now()) / 1_000)),
+    };
   }
 }
 
@@ -117,12 +95,15 @@ export class RateLimiter {
   }
 
   private profile(method: string, path: string): LimitProfile {
+    if (
+      method === "GET" &&
+      (path === "/api/auth/get-session" || path === "/site/settings")
+    ) {
+      return { name: "runtime", ttlSeconds: this.config.ttlSeconds, limit: this.config.runtimeLimit };
+    }
     if (path === "/api/auth" || path.startsWith("/api/auth/")) {
       return { name: "auth", ttlSeconds: this.config.authTtlSeconds, limit: this.config.authLimit };
     }
-    if (method === "GET" && path === "/site/settings") {
-      return { name: "runtime", ttlSeconds: this.config.ttlSeconds, limit: this.config.runtimeLimit };
-    }
     return { name: "general", ttlSeconds: this.config.ttlSeconds, limit: this.config.limit };
   }
 
@@ -152,7 +133,7 @@ export const rateLimitModule: PodokitModule = {
     const limiter = new RateLimiter(
       rateLimitConfig(),
       new RateLimitIdentity(services.resolve(API_KEY_VERIFIER), services),
-      new RedisRateLimitStorage(services.resolve(REDIS).client),
+      new CacheRateLimitStorage(services.resolve(CACHE)),
     );
     services.register(RATE_LIMITER, limiter);
     services.resolve(REQUEST_GUARDS).register((context) => limiter.enforce(context));

package/dist/templates/modules/rate-limit/files/tests/api/rate-limit.api.spec.ts

@@ -12,6 +12,7 @@ const origin = { origin: base };
 // value so the window is crossed in a handful of requests); otherwise fall back
 // to the module default and allow a little headroom.
 const limit = Number(process.env.RATE_LIMIT_MAX ?? 300);
+const authLimit = Number(process.env.RATE_LIMIT_AUTH_MAX ?? 20);
 
 async function session(
   playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"],
@@ -63,3 +64,14 @@ test("rate limit: health probes stay available while ordinary routes return 429
   });
   await ctx.dispose();
 });
+
+test("rate limit: session reads do not consume the strict authentication budget", async ({
+  playwright,
+}) => {
+  const ctx = await session(playwright);
+  for (let i = 0; i < authLimit + 5; i++) {
+    const response = await ctx.get("/api/auth/get-session");
+    expect(response.status(), `session request ${i + 1}`).toBe(200);
+  }
+  await ctx.dispose();
+});

package/dist/templates/modules/rate-limit/module.manifest.json

@@ -1,7 +1,9 @@
 {
   "name": "rate-limit",
-  "description": "Distributed Elysia request limiting by authenticated user, validated API key, or trusted-proxy client address. Uses Bun Redis across replicas and returns stable 429/503 errors.",
-  "requires": ["redis", "api-key-auth"],
+  "manifestVersion": 3,
+  "description": "Provider-neutral Elysia request limiting by authenticated user, validated API key, or trusted-proxy client address.",
+  "requires": ["api-key-auth"],
+  "requiresCapabilities": ["cache"],
   "targetApp": "api",
   "managedGlobs": [
     "apps/api/src/rate-limit/**",
@@ -15,7 +17,7 @@
     "# stricter authentication endpoint ceiling",
     "RATE_LIMIT_AUTH_TTL=60",
     "RATE_LIMIT_AUTH_MAX=20",
-    "# higher ceiling for SSR runtime settings reads",
+    "# higher ceiling for SSR runtime settings and session reads",
     "RATE_LIMIT_RUNTIME_MAX=1000",
     "# trust no proxy hop by default; set the exact production proxy depth",
     "RATE_LIMIT_TRUSTED_PROXY_HOPS=0",
@@ -36,14 +38,14 @@
     }
   ],
   "instructions": [
-    "Ensure Redis is running: docker compose -f infra/docker/docker-compose.yml up -d",
+    "Configure the selected cache provider before enabling request limits.",
     "Tune the general, authentication, and runtime limits in .env.",
     "Give each deployment that shares Redis a distinct RATE_LIMIT_KEY_PREFIX.",
     "Set RATE_LIMIT_TRUSTED_PROXY_HOPS to the exact number of trusted reverse proxies; keep 0 for direct API access.",
     "Authenticated users and validated X-API-Key clients receive independent opaque counters; other traffic uses the trusted client address.",
-    "Exceeded limits return RATE_LIMIT_EXCEEDED with HTTP 429 and Retry-After. Redis failures return RATE_LIMIT_UNAVAILABLE with HTTP 503.",
+    "Exceeded limits return RATE_LIMIT_EXCEEDED with HTTP 429 and Retry-After. Cache failures return RATE_LIMIT_UNAVAILABLE with HTTP 503.",
     "Register a RateLimitIdentityExtension under RATE_LIMIT_IDENTITY_EXTENSION in app.extensions.ts for another validated machine-key source.",
     "GET /health and GET /health/ready bypass request quotas so orchestrator probes remain reliable.",
-    "The atomic counter is shared across API replicas in Redis."
+    "Redis counters are shared across replicas; memory counters require one API replica."
   ]
 }

package/dist/templates/modules/redis/files/apps/api/src/redis/redis-cache.store.ts

@@ -0,0 +1,82 @@
+import type { RedisClient } from "bun";
+import type {
+  CacheSetOptions,
+  CacheStore,
+  FixedWindowOptions,
+  FixedWindowResult,
+} from "@podosoft/podokit-runtime";
+import type { RedisService } from "./redis.service";
+
+const FIXED_WINDOW_SCRIPT = `
+local count = redis.call('INCR', KEYS[1])
+if count == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+local ttl = redis.call('PTTL', KEYS[1])
+return { count, ttl }
+`;
+
+function resultNumber(value: unknown): number | undefined {
+  if (typeof value === "number") return value;
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+export class RedisCacheStore implements CacheStore {
+  private readonly client: RedisClient;
+
+  constructor(private readonly redis: RedisService) {
+    this.client = redis.client;
+  }
+
+  get(key: string): Promise<string | null> {
+    return this.redis.get(key);
+  }
+
+  async set(key: string, value: string, options: CacheSetOptions = {}): Promise<void> {
+    await this.client.set(key, value);
+    if (options.ttlMs !== undefined) {
+      if (!Number.isSafeInteger(options.ttlMs) || options.ttlMs < 1) {
+        throw new Error("ttlMs must be a positive integer");
+      }
+      await this.client.send("PEXPIRE", [key, String(options.ttlMs)]);
+    }
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return (await this.redis.del(key)) > 0;
+  }
+
+  async incrementFixedWindow(
+    key: string,
+    options: FixedWindowOptions,
+  ): Promise<FixedWindowResult> {
+    if (!Number.isSafeInteger(options.windowMs) || options.windowMs < 1) {
+      throw new Error("windowMs must be a positive integer");
+    }
+    if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
+      throw new Error("limit must be a positive integer");
+    }
+    const result = await this.client.send("EVAL", [
+      FIXED_WINDOW_SCRIPT,
+      "1",
+      key,
+      String(options.windowMs),
+    ]);
+    if (!Array.isArray(result)) throw new Error("Redis returned an invalid cache counter");
+    const count = resultNumber(result[0]);
+    const ttlMs = resultNumber(result[1]);
+    if (count === undefined || ttlMs === undefined) {
+      throw new Error("Redis returned an invalid cache counter");
+    }
+    return {
+      allowed: count <= options.limit,
+      count,
+      remaining: Math.max(0, options.limit - count),
+      resetAt: Date.now() + Math.max(1, ttlMs),
+    };
+  }
+
+  close(): void {}
+}

package/dist/templates/modules/redis/files/apps/api/src/redis/redis.module.ts

@@ -1,4 +1,6 @@
 import { Elysia, t } from "elysia";
+import { CACHE } from "@podosoft/podokit-runtime";
+import { PROVIDERS } from "../config/providers";
 import {
   type AppPlugin,
   type PodokitModule,
@@ -6,10 +8,12 @@ import {
   type ServiceKey,
 } from "../core/services";
 import { RedisService } from "./redis.service";
+import { RedisCacheStore } from "./redis-cache.store";
 
 export const REDIS = Symbol("redis") as ServiceKey<RedisService>;
 
 const cachePlugin: AppPlugin = ({ services }) => {
+  if (PROVIDERS.cache !== "redis") return new Elysia({ name: "podokit.redis.inactive" });
   const redis = services.resolve(REDIS);
   return new Elysia({ name: "podokit.redis" })
     .put("/cache/:key", async ({ params, body }) => {
@@ -35,8 +39,10 @@ const cachePlugin: AppPlugin = ({ services }) => {
 export const redisModule: PodokitModule = {
   name: "redis",
   configure: (_env, services): void => {
+    if (PROVIDERS.cache !== "redis") return;
     const redis = new RedisService(services.resolve(READINESS));
     services.register(REDIS, redis, () => redis.close());
+    services.register(CACHE, new RedisCacheStore(redis));
     services.onStart(() => redis.connect());
   },
   plugin: cachePlugin,

package/dist/templates/modules/redis/module.manifest.json

@@ -1,7 +1,9 @@
 {
+  "manifestVersion": 3,
   "name": "redis",
   "description": "Bun native Redis client with get/set/del and publish/subscribe, plus demo cache endpoints.",
   "requires": [],
+  "provides": { "cache": "redis" },
   "requiredProjectFiles": [
     "apps/api/src/config/redis.connection.ts",
     "apps/api/src/health/readiness.service.ts"

package/dist/templates/modules/sse/files/apps/api/src/events/events.module.ts

@@ -1,18 +1,17 @@
 import { AppException } from "@podosoft/podokit-contracts";
+import { EVENTS } from "@podosoft/podokit-runtime";
 import { Elysia, sse, t } from "elysia";
 import {
   type AppPlugin,
   type PodokitModule,
   READINESS,
-  type ServiceKey,
 } from "../core/services";
 import { EventsService } from "./events.service";
-import { createEventsTransport } from "./events.transport";
 
-export const EVENTS = Symbol("events") as ServiceKey<EventsService>;
+export const SSE_EVENTS = Symbol("sse-events") as import("../core/services").ServiceKey<EventsService>;
 
 const eventsPlugin: AppPlugin = ({ services }) => {
-  const events = services.resolve(EVENTS);
+  const events = services.resolve(SSE_EVENTS);
   return new Elysia({ name: "podokit.events" })
     .get("/events/stream", async function* ({ request }) {
       for await (const data of events.stream(request.signal)) yield sse({ data });
@@ -40,8 +39,8 @@ const eventsPlugin: AppPlugin = ({ services }) => {
 export const eventsModule: PodokitModule = {
   name: "sse",
   configure: (_env, services): void => {
-    const events = new EventsService(createEventsTransport(), services.resolve(READINESS));
-    services.register(EVENTS, events, () => events.close());
+    const events = new EventsService(services.resolve(EVENTS), services.resolve(READINESS));
+    services.register(SSE_EVENTS, events, () => events.close());
     services.onStart(() => events.connect());
   },
   plugin: eventsPlugin,

package/dist/templates/modules/sse/files/apps/api/src/events/events.service.spec.ts

@@ -1,12 +1,12 @@
 import { describe, expect, it } from "bun:test";
 import { ReadinessService } from "../health/readiness.service";
+import { MemoryEventBus } from "@podosoft/podokit-runtime";
 import { EventsService } from "./events.service";
-import { MemoryEventsTransport } from "./events.transport";
 
 describe("EventsService", () => {
   it("publishes through the transport and delivers locally", async () => {
     const readiness = new ReadinessService();
-    const service = new EventsService(new MemoryEventsTransport(), readiness);
+    const service = new EventsService(new MemoryEventBus(), readiness);
     const received: unknown[] = [];
     service.subscribe((data) => received.push(data));
     await service.connect();
@@ -18,12 +18,12 @@ describe("EventsService", () => {
 
   it("rejects events larger than the configured limit", async () => {
     const service = new EventsService(
-      new MemoryEventsTransport({ SSE_MAX_EVENT_BYTES: "8" }),
+      new MemoryEventBus({ maxEventBytes: 8 }),
       new ReadinessService(),
     );
     await service.connect();
     await expect(service.publishAsync({ message: "too large" })).rejects.toThrow(
-      "Event data exceeds SSE_MAX_EVENT_BYTES",
+      "Event exceeds maxEventBytes",
     );
     await service.close();
   });

package/dist/templates/modules/sse/files/apps/api/src/events/events.service.ts

@@ -1,19 +1,20 @@
 import { ReadinessService } from "../health/readiness.service";
-import type { EventsTransport } from "./events.transport";
+import type { EventBus, Unsubscribe } from "@podosoft/podokit-runtime";
 
 type LocalHandler = (data: unknown) => void;
 
 export class EventsService {
   private readonly handlers = new Set<LocalHandler>();
   private unregisterReadiness?: () => void;
+  private unsubscribe?: Unsubscribe;
 
   constructor(
-    private readonly transport: EventsTransport,
+    private readonly transport: EventBus,
     private readonly readiness: ReadinessService,
   ) {}
 
   async connect(): Promise<void> {
-    await this.transport.connect((data) => this.publishLocal(data));
+    this.unsubscribe = await this.transport.subscribe("sse", (data) => this.publishLocal(data));
     this.unregisterReadiness = this.readiness.register("events", () => this.transport.ready());
   }
 
@@ -25,7 +26,7 @@ export class EventsService {
   }
 
   publishAsync(data: unknown): Promise<void> {
-    return this.transport.publish(data);
+    return this.transport.publish("sse", data);
   }
 
   publishLocal(data: unknown): void {
@@ -66,7 +67,7 @@ export class EventsService {
 
   async close(): Promise<void> {
     this.unregisterReadiness?.();
+    await this.unsubscribe?.();
     this.handlers.clear();
-    await this.transport.close();
   }
 }

package/dist/templates/modules/sse/module.manifest.json

@@ -1,16 +1,14 @@
 {
+  "manifestVersion": 3,
   "name": "sse",
   "description": "Server-Sent Events with memory or Redis transport for multi-replica delivery.",
-  "requires": [],
+  "requiresCapabilities": ["events"],
   "requiredProjectFiles": [
-    "apps/api/src/config/redis.connection.ts",
     "apps/api/src/health/readiness.service.ts"
   ],
   "targetApp": "api",
   "env": [
-    "# Server-Sent Events transport: memory for one API replica, redis for multiple replicas",
-    "SSE_TRANSPORT=memory",
-    "SSE_REDIS_CHANNEL=podokit:events",
+    "# Maximum encoded Server-Sent Event payload",
     "SSE_MAX_EVENT_BYTES=65536"
   ],
   "inject": [
@@ -20,7 +18,7 @@
   "instructions": [
     "Stream events:  curl -N localhost:5002/events/stream",
     "Publish a message (in another terminal):  curl -XPOST localhost:5002/events -H 'content-type: application/json' -d '{\"message\":\"hello\"}'",
-    "Set SSE_TRANSPORT=redis for delivery across API replicas; Redis uses the shared REDIS_URL or individual Redis settings.",
+    "Select events=redis for multiple replicas or events=memory for a single process.",
     "Inject EventsService and call publishAsync for confirmed delivery, publish for best-effort delivery, or publishLocal for events already fanned out to every replica."
   ]
 }

package/dist/templates/todo/AGENTS.md

@@ -8,26 +8,44 @@ Follow it so your changes match the project's conventions.
 
 A Bun 1.4 full-stack TypeScript monorepo ({{packageManager}} workspaces):
 
-- `apps/api` — **Elysia** backend (`{{projectName}}-api`), Bun.SQL + PostgreSQL, merged OpenAPI at `/api-docs`.
+- `apps/api` — **Elysia** backend (`{{projectName}}-api`), Bun.SQL + `{{databaseProvider}}`, merged OpenAPI at `/api-docs`.
 - `apps/web` — **SvelteKit** frontend (`{{projectName}}-web`), Tailwind v4 + shadcn-svelte + typesafe-i18n.
-- `infra/` — Docker Compose (PostgreSQL/Redis) and example k3s manifests.
-- `.podokit/` — PodoKit's generation lockfile (see "PodoKit tooling" below). Do not edit by hand.
+- `infra/` — Docker Compose references for external services and example k3s manifests.
+- `.podokit/` — generation metadata plus application-owned development and deployment profiles.
 - **Todo example**: `apps/api/src/todos/` (Elysia plugin, Bun.SQL repository, and migration) and the todo UI in `apps/web/src/routes/` show the end-to-end patterns to follow.
 
 ## Setup & commands
 
+Inspect active infrastructure with `podo provider list`. New-project defaults
+are `database=postgres`, `cache=redis`, `object-storage=s3`, `events=redis`, and
+`jobs=bullmq`. A simple single-process app can instead use `sqlite`, `memory`
+cache/events, `local` files, and `local` jobs. Only the database has a creation
+flag (`--database`); apply other choices using
+`podo provider set <capability> <provider> --apply` before adding features.
+Provider selection does not migrate or delete existing data.
+
 ```bash
 {{packageManager}} install
 cp .env.example .env
-docker compose -f infra/docker/docker-compose.yml up -d   # PostgreSQL (+ Redis)
+{{apiRun}} migration:run
 {{rootRun}} dev        # api on http://localhost:5002, web on http://localhost:5001
 ```
 
+For PostgreSQL, start `docker compose -f infra/docker/docker-compose.yml up -d`
+before migrating. Add `--profile cache` for Redis; Silo uses the overlay from
+`object-storage-s3`. Skip external services entirely for the complete local
+combination. `podo dev watch` is a separate container workflow and requires
+Docker. SQLite and local files default to `./data/podokit.sqlite` and
+`./data/files` relative to the API working directory; migrations and runtime
+must use the same database path. Keep local providers at one API process.
+Merge added module settings from `.env.example` into an existing `.env`.
+
 - **Ports: web = 5001, api = 5002.** The web app reaches the API only through its
   SvelteKit server proxy (`/api/*`), never with a direct browser `fetch`.
 - Build: `{{rootRun}} build`  ·  Type-check/lint: `{{rootRun}} lint`  ·  Unit tests: `{{rootRun}} test`
 - Per workspace: `{{apiRun}} build` / `{{webRun}} build`.
-- DB migrations (TypeORM migration layer only): `{{apiRun}} migration:run`.
+- Application migrations (PostgreSQL or SQLite): `{{apiRun}} migration:run`.
+- When `auth` is installed, run `{{apiRun}} migrate:all` for Better Auth and application tables.
 - e2e (Playwright, ships in `tests/`): `{{rootRun}} test:e2e`.
 - Playwright officially runs on Node, so `bunx playwright` respects its Node
   shebang. Node LTS is a test-tool dependency only; API, web, worker, migrations,
@@ -69,11 +87,12 @@ in `.podokit/files.lock` — respect it:
 
 Useful commands:
 
+- `podo provider list` / `podo provider set <capability> <provider> [--apply]` — inspect or switch database, cache, storage, events, and jobs; set previews by default.
 - `podo add <module>` — add a feature (auth, admin-dashboard, redis, bullmq, …). It wires itself into the app; run `podo add` with no argument to list modules.
 - `podo remove <module>` — un-apply a module (inverse of add; refuses if another module needs it, keeps files you edited).
 - `podo status` / `podo diff` — see your local edits vs. what PodoKit generated.
 - `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
-- `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.
+- `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Production API WebSocket paths belong in the deployment profile's exact `exposure.webSocketPaths` allowlist; Compose trusts forwarding headers only from `exposure.trustedProxyCidrs`. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.
 - `podo deploy sync` — copy local build output into a running Compose deployment and restart it, for iterating without a release. Not a release: no image is published and the next `apply` discards it. Use `.agents/skills/podokit-deploy-fast`.
 
 ## Commit conventions

package/dist/templates/todo/README.md

@@ -2,9 +2,47 @@
 
 Full-stack TypeScript app generated with [PodoKit](https://github.com/podosoft-dev/podokit).
 
-- `apps/api` — Bun 1.4 + Elysia API: schema-validated env, `/health` + `/health/ready`, a Bun.SQL Todo CRUD resource backed by PostgreSQL, merged OpenAPI at `/api-docs`, and a standard error envelope.
+- `apps/api` — Bun 1.4 + Elysia API: schema-validated env, `/health` + `/health/ready`, a Bun.SQL Todo CRUD resource backed by PostgreSQL or SQLite, merged OpenAPI at `/api-docs`, and a standard error envelope.
 - `apps/web` — SvelteKit app (TailwindCSS v4, shadcn-svelte, typesafe-i18n) with a todo UI that talks to the API through a server-side proxy.
-- `infra/` — Docker Compose (PostgreSQL, Redis) and k3s manifests.
+- `infra/` — Docker Compose references for external services and k3s manifests.
+
+## Infrastructure choices
+
+Inspect the current selections with `{{packageExecutor}} @podosoft/podokit provider list`.
+New projects use these defaults unless configured otherwise:
+
+| Capability | Default | Lightweight alternative |
+| --- | --- | --- |
+| Database | `postgres` | `sqlite` |
+| Cache | `redis` | `memory` |
+| Object storage | `s3` | `local` |
+| Events | `redis` | `memory` |
+| Jobs | `bullmq` | `local` |
+
+For a simple program, prototype, or desktop app, SQLite, memory cache/events,
+local files, and local jobs can run inside one API process without PostgreSQL,
+Redis, or S3 services. `create --database sqlite` selects only the database;
+choose the other providers after creation:
+
+```bash
+{{packageExecutor}} @podosoft/podokit provider set cache memory --apply
+{{packageExecutor}} @podosoft/podokit provider set object-storage local --apply
+{{packageExecutor}} @podosoft/podokit provider set events memory --apply
+{{packageExecutor}} @podosoft/podokit provider set jobs local --apply
+```
+
+Apply providers before adding features, then install dependencies and merge new
+`.env.example` entries into `.env`. These commands install implementation modules
+and configure them; they do not move or delete data. SQLite defaults to
+`./data/podokit.sqlite`, and local files to `LOCAL_STORAGE_PATH=./data/files`,
+relative to the API working directory. Memory cache/events are lost on restart;
+the database, files, and local job records persist. Use absolute paths and back
+up the database and files together for packaged or production apps.
+
+Use the host-process setup below to avoid Docker. The containerized loop still
+requires Docker. See the PodoKit
+[runtime provider guide](https://github.com/podosoft-dev/podokit/blob/main/docs/providers.md)
+for server settings, Silo/AWS S3 configuration, and provider switching.
 
 ## Getting started
 
@@ -40,7 +78,7 @@ In a second terminal, apply the included Todo migration and use the lifecycle he
 ```
 
 `dev watch` reads `.podokit/manifest.json` and automatically activates `cache`,
-`storage`, and `queue` when installed modules require Redis, MinIO, or a worker.
+`storage`, and `queue` when installed modules require Redis, Silo, or a worker.
 `dev up` uses the same shared gateway and module profiles without keeping Compose
 Watch attached.
 You can still activate an additional Compose profile explicitly:
@@ -57,17 +95,27 @@ through Compose Watch, including Vite HMR on the same portless browser origin.
 
 ### Alternative: host processes
 
-Use this loop when you want only the web and API processes on the host:
+Use this loop for an app with SQLite and local providers, or when you want the
+web and API processes on the host. Prepare the project first:
 
 ```bash
-# start local PostgreSQL + Redis
-docker compose -f infra/docker/docker-compose.yml up -d
-
-# run database migrations
+{{packageManager}} install
+cp .env.example .env
 {{apiRun}} migration:run
+```
+
+For PostgreSQL, start `docker compose -f infra/docker/docker-compose.yml up -d`
+before migrating. Redis needs `--profile cache`; Silo needs the storage overlay
+added by `object-storage-s3`. Skip those services for the complete local setup.
+
+Run each service in a separate terminal from the project root:
+
+```bash
+{{apiRun}} dev # terminal 1
+```
 
-# run api + web
-{{packageManager}} run dev
+```bash
+{{webRun}} dev # terminal 2
 ```
 
 - API: http://localhost:5002 — health at `/health`, docs at `/api-docs`
@@ -78,18 +126,28 @@ tunnel, see the PodoKit [development guide](https://github.com/podosoft-dev/podo
 
 ## Database & migrations
 
-The API uses Bun.SQL with PostgreSQL. TypeORM is limited to the migration layer;
-a sample Todo repository and initial migration are included.
+The API uses Bun.SQL with the selected PostgreSQL or SQLite database. TypeORM
+runs PostgreSQL migrations; SQLite uses the local migration runner. A sample
+Todo repository and initial migration are included.
 
 ```bash
 {{apiRun}} migration:run      # apply migrations
 {{apiRun}} migration:revert   # roll back the last one
 ```
 
+When `auth` is installed, use `{{apiRun}} migrate:all` to create or update both
+Better Auth and application tables. Set the module's required environment
+values before migrating.
+
 ## Deploy
 
 Docker Compose lives in `infra/docker`; the basic k3s manifests in `infra/k3s`
 route every public path through the web proxy. Use `podo deploy init`, `doctor`,
-and `plan` for an exact-image Helm release on an existing cluster. Applying or
-rolling back requires the exact confirmation hash from a fresh plan. See the
+and `plan` for an exact-image release on Kubernetes or one Docker host. Applying
+or rolling back requires the exact confirmation hash from a fresh plan. See the
 PodoKit [deployment guide](https://github.com/podosoft-dev/podokit/blob/main/docs/deployment.md).
+
+For a Docker Compose deployment with API WebSockets, list their exact paths under
+`exposure.webSocketPaths`. The driver keeps one published port, routes those paths
+to API, and sends every other request to web. If an external reverse proxy supplies
+forwarding headers, list only its direct CIDR blocks in `exposure.trustedProxyCidrs`.

package/dist/templates/todo/apps/api/src/migrations/1720100000000-InitTodos.ts

@@ -4,6 +4,17 @@ export class InitTodos1720100000000 implements MigrationInterface {
   name = "InitTodos1720100000000";
 
   async up(queryRunner: QueryRunner): Promise<void> {
+    if (queryRunner.connection.options.type === "better-sqlite3") {
+      await queryRunner.query(`
+        CREATE TABLE "todos" (
+          "id" text NOT NULL PRIMARY KEY,
+          "title" character varying(500) NOT NULL,
+          "completed" boolean NOT NULL DEFAULT false,
+          "createdAt" text NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+        )
+      `);
+      return;
+    }
     await queryRunner.query(`CREATE EXTENSION IF NOT EXISTS "pgcrypto"`);
     await queryRunner.query(`
       CREATE TABLE "todos" (