@zaaxch/tailframe 2.2.0 → 3.0.0

package/src/new.mjs

@@ -1,6 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { authAppStoreSource, GenerateError } from "./generate.mjs";
+import { configSource } from "./config.mjs";
+import { ownedSources } from "./owned-sources.mjs";
+import { runSync } from "./sync.mjs";
 import {
 	appErrorSource,
 	applicationRoutesSource,
@@ -16,6 +19,7 @@ import {
 	healthSchemasSource,
 	httpErrorsSource,
 	mongoReadinessProbeSource,
+	postgresReadinessProbeSource,
 	readinessProbeSource,
 	redisReadinessProbeSource,
 	redisSource,
@@ -42,13 +46,14 @@ function parseArgs(argv) {
 	const result = { db: "mongo", auth: "none", ui: false, redis: false, worker: false };
 	for (let i = 0; i < argv.length; i += 1) {
 		const arg = argv[i];
-		if (["--name", "--path", "--auth"].includes(arg)) result[arg.slice(2)] = argv[++i];
+		if (["--name", "--path", "--auth", "--db"].includes(arg)) result[arg.slice(2)] = argv[++i];
 		else if (["--ui", "--redis", "--worker"].includes(arg)) result[arg.slice(2)] = true;
 		else fail(`Unknown argument: ${arg}`);
 	}
 	if (!result.name || !/^[a-z][a-z0-9-]*$/.test(result.name)) fail("--name must use lowercase letters, digits, and hyphens and start with a letter");
 	if (!result.path) fail("--path is required");
 	if (!["none", "firebase"].includes(result.auth)) fail("--auth must be none or firebase");
+	if (!["mongo", "postgres"].includes(result.db)) fail("--db must be mongo or postgres");
 	if (result.worker) result.redis = true;
 	return result;
 }
@@ -64,6 +69,7 @@ const title = options.name.split("-").map((part) => part[0].toUpperCase() + part
 const svc = `${options.name}-svc`;
 const ui = `${options.name}-ui`;
 const databaseName = options.name.replaceAll("-", "_");
+const postgres = options.db === "postgres";
 const mongoApplicationUser = `${options.name}-app`;
 const mongoBackupUser = `${options.name}-backup`;
 const files = {};
@@ -71,6 +77,13 @@ const add = (relative, content) => { files[relative] = content.endsWith("\n") ?
 // Generated repositories depend on the published toolkit rather than copying a validator, and they
 // pin the exact contract version they were generated against.
 const contractVersion = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const serviceProfiles = [
+	...(options.auth === "firebase" ? ["firebase"] : []),
+	options.db,
+	...(options.redis ? ["redis", "rate-limit"] : []),
+	...(options.worker ? ["worker"] : []),
+	...(options.ui ? ["ui-host"] : [])
+];
 const prettierConfig = {
 	useTabs: true,
 	tabWidth: 4,
@@ -169,13 +182,13 @@ Use this workflow for any new domain capability or operation. Add only the layer
 2. Read the root and every applicable child \`AGENTS.md\`.
 3. Inspect the nearest working module and tests.
 4. Create architecture files only with the tailframe CLI: \`tailframe generate\` creates service modules, use cases, http files, ports, adapters, identifiers, integrations, UI modules, and the closed UI shell catalog on canonical paths with canonical names. Service module generation also registers the new use case and mounts or extends its single route factory through deterministic composition-file edits. Hand-creating architecture files or editing generated shell-catalog implementations is a conformance violation; inspect the generated diff and complete only the remaining behavior-specific checklist.
-5. Colocate product capability behavior under \`src/modules/<module>\` in both the service and UI. Never substitute \`features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories. UI \`app/stores\` is closed to generated \`auth.store.ts\` and \`theme.store.ts\`; \`app/public\` is closed to generated \`ThemeToggle.vue\`. Never create \`src/modules/theme\` or \`src/modules/auth\`. Product records, current-user domain records, selections, filters, and workflows stay in their owning module. Start backend modules with \`use-cases/\`, \`http/\`, and tests; add \`domain/\` or \`persistence/\` only when required. Add only the UI module directories earned by the capability.
+5. Colocate product capability behavior under \`src/modules/<module>\` in both the service and UI. Never substitute \`features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories. UI \`app/stores\` is closed to generated \`auth.store.ts\`, \`notification.store.ts\`, and \`theme.store.ts\`; \`app/public\` is closed to generated \`ThemeToggle.vue\`. Never create \`src/modules/theme\`, \`src/modules/auth\`, or \`src/modules/notification\`. Product records, current-user domain records, selections, filters, and workflows stay in their owning module. Start backend modules with \`use-cases/\`, \`http/\`, and tests; add \`domain/\` or \`persistence/\` only when required. Add only the UI module directories earned by the capability.
 6. Define use cases as \`execute(context, input)\`. Keep trusted \`RequestContext\` separate from client input.
 7. Put ownership, RBAC, entitlements, and domain policies in use-case or domain code, not client bodies or route metadata.
 8. Define repository contracts in the owning module and implement them in persistence adapters.
 9. For persisted capabilities, prefer branded, domain-owned string IDs at domain and repository-port boundaries; generate the module's identifier file with \`tailframe generate identifiers <module> <NameId...>\`. Keep MongoDB \`ObjectId\` conversion inside MongoDB persistence adapters, using persistence-only document types rather than \`any\` to bypass the boundary.
 10. Let HTTP routes, jobs, workers, scheduled tasks, and CLIs invoke use cases directly; do not call one entry point from another.
-11. Keep operation names, payloads, authentication, response contracts, and client types synchronized. A service module may import another only through a named file directly under the provider's use-cases directory. A UI module may import another only through a named file directly under the provider's public directory. Both graphs must remain acyclic. UI modules may import only the generated auth/theme app stores and \`ThemeToggle\` from app; every other app path is private.
+11. Keep operation names, payloads, authentication, response contracts, and client types synchronized. A service module may import another only through a named file directly under the provider's use-cases directory. A UI module may import another only through a named file directly under the provider's public directory. Both graphs must remain acyclic. UI modules may import only the generated auth/notification/theme app stores and \`ThemeToggle\` from app; every other app path is private.
 12. Verify generated container and route wiring, then add only dependency construction, client, navigation, worker, or process registration earned by real behavior. Route module views directly from \`app/router.ts\`. App views and shell components consume product modules only through named module \`public/\` entries; they never import module views or other internals.
 13. Run npm run validate:architecture in every affected repository, then run focused type checks and tests. Report repositories, operations, entry points, checks, placement decisions, and gaps.
 
@@ -189,12 +202,13 @@ const svcDeps = {
 	joi: "^17.13.3",
 	"reflect-metadata": "^0.2.2",
 	tsyringe: "^4.9.1",
-	mongodb: "^6.17.0",
+	...(postgres ? { pg: "^8.16.3" } : { mongodb: "^6.17.0" }),
 	...(options.auth === "firebase" ? { "firebase-admin": "^13.0.0" } : {}),
-	...(options.redis ? { redis: "^5.10.0" } : {})
+	...(options.redis ? { "rate-limiter-flexible": "^11.2.0", redis: "^5.10.0" } : {})
 };
 const svcDevDeps = {
 	"@types/cors": "^2.8.17", "@types/express": "^5.0.1", "@types/jest": "^30.0.0", "@types/node": "^22.13.14", "@types/supertest": "^7.2.1",
+	...(postgres ? { "@types/pg": "^8.15.5" } : {}),
 	"@zaaxch/tailframe": contractVersion,
 	jest: "^30.0.0", nodemon: "^3.1.9", prettier: "3.5.3", "ts-jest": "^29.4.11", "ts-node": "^10.9.2",
 	"tsc-alias": "^1.8.16", "tsconfig-paths": "^4.2.0", typescript: "^5.8.2", supertest: "^7.2.2"
@@ -207,13 +221,15 @@ add(`${svc}/package.json`, JSON.stringify({
 		...(options.worker ? { "dev:worker": "nodemon --legacy-watch --exec ts-node -r tsconfig-paths/register src/worker.ts" } : {}),
 		build: "tsc && tsc-alias", start: "node dist/server.js",
 		...(options.worker ? { worker: "node dist/worker.js" } : {}),
-		test: "npm run test:unit && npm run test:integration", "test:unit": "jest --selectProjects unit --runInBand", "test:integration": "jest --selectProjects integration --runInBand", "validate:architecture": "tailframe validate --kind service .", format: "prettier --write src/", "format:check": "prettier --check src/",
+		test: "npm run test:unit && npm run test:integration", "test:unit": "jest --selectProjects unit --runInBand", "test:integration": "jest --selectProjects integration --runInBand", "validate:architecture": "tailframe validate .", "sync:architecture": "tailframe sync --check .", format: "prettier --write src/", "format:check": "prettier --check src/",
+		"schema:apply": "node dist/app/cli/applySchema.js", "schema:apply:dev": "ts-node -r tsconfig-paths/register src/app/cli/applySchema.ts",
 		"test:db:up": "docker compose -f docker-compose.test.yml up -d", "test:db:down": "docker compose -f docker-compose.test.yml down -v",
 		"docker:dev": "docker compose -f docker-compose.dev.yml up",
 		"docker:prod": "docker compose -f docker-compose.yml up -d",
 		"docker:push": "bash scripts/build_and_push.sh"
 	}, dependencies: svcDeps, devDependencies: svcDevDeps
 }, null, "\t"));
+add(`${svc}/tailframe.json`, configSource({ kind: "service", profiles: serviceProfiles, contractVersion }));
 add(`${svc}/tsconfig.json`, JSON.stringify({
 	compilerOptions: { target: "ES2022", module: "commonjs", rootDir: "src", outDir: "dist", strict: true, esModuleInterop: true, experimentalDecorators: true, emitDecoratorMetadata: true, baseUrl: ".", paths: { "@/*": ["src/*"] }, skipLibCheck: true },
 	include: ["src/**/*.ts"]
@@ -228,17 +244,23 @@ add(`${svc}/.gitattributes`, gitAttributes);
 add(`${svc}/.gitignore`, `node_modules/\ndist/\n.env*\n!.env.example\n!.env.infrastructure.example\n*.log\nfirebase-service-account*.json\n`);
 add(`${svc}/.dockerignore`, `node_modules\ndist\n.git\n.env*\n!.env.example\n*.log\ndata\nfirebase-service-account*.json\n`);
 if (options.ui) add(".dockerignore", `**/node_modules\n**/dist\n**/.git\n**/.env*\n**/*.log\n**/data\n**/firebase-service-account*.json\n`);
-const dbEnv = "MONGODB_URI=mongodb://localhost:27017/?replicaSet=rs0&directConnection=true\nMONGODB_DB_NAME=" + databaseName;
+const dbEnv = postgres
+	? `POSTGRES_URI=postgresql://${options.name}-app:development@localhost:5432/${databaseName}`
+	: "MONGODB_URI=mongodb://localhost:27017/?replicaSet=rs0&directConnection=true\nMONGODB_DB_NAME=" + databaseName;
 add(`${svc}/.env.example`, `NODE_ENV=development\nPORT=3000\nCORS_ORIGIN=https://localhost:5173\n${dbEnv}\n${options.auth === "firebase" ? "FIREBASE_PROJECT_ID=\n" : ""}${options.redis ? "REDIS_URL=redis://localhost:6379\n" : ""}`);
 add(`${svc}/.env.infrastructure.example`, `ECR_IMAGE=<account>.dkr.ecr.<region>.amazonaws.com/${options.name}
 IMAGE_TAG=<service-sha>${options.ui ? "_<ui-sha>" : ""}
 APP_ENV_FILE=/opt/${options.name}/shared/.env.production
-MONGO_DATA_DIR=/opt/${options.name}/shared/mongo/data
+${postgres ? `POSTGRES_DATA_DIR=/opt/${options.name}/shared/postgres/data
+POSTGRES_ROOT_PASSWORD=<uri-safe-random-value>
+POSTGRES_APP_PASSWORD=<different-uri-safe-random-value>
+` : `MONGO_DATA_DIR=/opt/${options.name}/shared/mongo/data
 MONGO_KEYFILE=/opt/${options.name}/shared/mongo/config/keyfile
 MONGO_INIT_SCRIPT=/opt/${options.name}/current/deploy/mongo/10-create-users.js
 MONGODB_ROOT_PASSWORD=<uri-safe-random-value>
 MONGODB_APP_PASSWORD=<different-uri-safe-random-value>
 MONGODB_BACKUP_PASSWORD=<different-uri-safe-random-value>
+`}
 ${options.auth === "firebase" ? `SECRETS_DIR=/opt/${options.name}/shared/secrets
 ` : ""}${options.redis ? `REDIS_DATA_DIR=/opt/${options.name}/shared/redis/data
 REDIS_PASSWORD=<different-uri-safe-random-value>
@@ -248,12 +270,25 @@ export const env = {
 	nodeEnv: process.env.NODE_ENV ?? "development",
 	port: Number(process.env.PORT ?? 3000),
 	corsOrigin: process.env.CORS_ORIGIN ?? "https://localhost:5173",
-	${options.auth === "firebase" ? `firebaseProjectId: process.env.FIREBASE_PROJECT_ID ?? "",` : ""}
-	mongodbUri: process.env.MONGODB_URI ?? "mongodb://localhost:27017/?replicaSet=rs0&directConnection=true",
-	mongodbDbName: process.env.MONGODB_DB_NAME ?? "${databaseName}",
+	${options.auth === "firebase" ? `firebaseProjectId: process.env.FIREBASE_PROJECT_ID ?? "",
+	firebaseServiceAccountPath: process.env.FIREBASE_SERVICE_ACCOUNT_PATH,` : ""}
+	${postgres ? `postgresUri: process.env.POSTGRES_URI ?? "postgresql://${options.name}-app:development@localhost:5432/${databaseName}",` : `mongodbUri: process.env.MONGODB_URI ?? "mongodb://localhost:27017/?replicaSet=rs0&directConnection=true",
+	mongodbDbName: process.env.MONGODB_DB_NAME ?? "${databaseName}",`}
 	${options.redis ? `redisUrl: process.env.REDIS_URL ?? "redis://localhost:6379",` : ""}
 };`);
-const databaseSource = `import { MongoClient } from "mongodb";
+const databaseSource = postgres ? `import { Pool } from "pg";
+import { env } from "@/platform/config/env";
+
+export const postgres = new Pool({ connectionString: env.postgresUri });
+
+export async function connectDatabase() {
+	await postgres.query("SELECT 1");
+	return postgres;
+}
+
+export async function closeDatabase() {
+	await postgres.end();
+}` : `import { MongoClient } from "mongodb";
 import { env } from "@/platform/config/env";
 
 export const mongo = new MongoClient(env.mongodbUri);
@@ -267,6 +302,15 @@ export async function closeDatabase() {
 	await mongo.close();
 }`;
 add(`${svc}/src/platform/database/index.ts`, databaseSource);
+add(`${svc}/src/app/schema.ts`, `import type { SchemaLifecycle } from "@/core/SchemaLifecycle";
+import { closeDatabase, connectDatabase } from "@/platform/database";
+
+export const schemaLifecycle: SchemaLifecycle = {
+	async apply() {
+		await connectDatabase();
+	},
+	close: closeDatabase
+};`);
 if (options.redis) add(`${svc}/src/platform/redis/index.ts`, redisSource);
 add(`${svc}/src/core/RequestContext.ts`, requestContextSource);
 add(`${svc}/src/core/UseCase.ts`, useCaseSource);
@@ -283,9 +327,10 @@ add(`${svc}/src/modules/health/use-cases/GetReadiness.ts`, getReadinessSource);
 add(`${svc}/src/modules/health/use-cases/ports/ReadinessProbe.ts`, readinessProbeSource);
 add(`${svc}/src/modules/health/http/health.schemas.ts`, healthSchemasSource);
 add(`${svc}/src/modules/health/http/health.routes.ts`, healthRoutesSource);
-add(`${svc}/src/platform/integrations/mongodb/MongoReadinessProbe.ts`, mongoReadinessProbeSource);
+if (postgres) add(`${svc}/src/platform/integrations/postgres/PostgresReadinessProbe.ts`, postgresReadinessProbeSource);
+else add(`${svc}/src/platform/integrations/mongodb/MongoReadinessProbe.ts`, mongoReadinessProbeSource);
 if (options.redis) add(`${svc}/src/platform/integrations/redis/RedisReadinessProbe.ts`, redisReadinessProbeSource);
-add(`${svc}/src/app/container.ts`, containerSource({ redis: options.redis }));
+add(`${svc}/src/app/container.ts`, containerSource({ database: options.db, redis: options.redis }));
 add(`${svc}/src/app/routes.ts`, applicationRoutesSource);
 add(`${svc}/src/app/server.ts`, serverSource({ ui: options.ui, redis: options.redis, csrf }));
 add(`${svc}/src/server.ts`, `import "reflect-metadata";\nimport { startServer } from "@/app/server";\nvoid startServer();\n`);
@@ -293,13 +338,34 @@ if (options.worker) add(`${svc}/src/app/workers/startWorker.ts`, workerSource())
 if (options.worker) add(`${svc}/src/worker.ts`, `import "reflect-metadata";\nimport { startWorker } from "@/app/workers/startWorker";\nvoid startWorker();\n`);
 add(`${svc}/src/modules/health/__tests__/GetHealth.test.ts`, getHealthTestSource);
 add(`${svc}/src/modules/health/__tests__/GetReadiness.test.ts`, getReadinessTestSource);
-add(`${svc}/src/__tests__/testDb.ts`, `import { MongoClient } from "mongodb";
+add(`${svc}/src/__tests__/testDb.ts`, postgres ? `import { Pool } from "pg";
+const pool = new Pool({ connectionString: process.env.TEST_POSTGRES_URI ?? "postgresql://postgres:postgres@localhost:5433/${databaseName}_test" });
+export async function openTestDatabase() { await pool.query("SELECT 1"); return pool; }
+export async function resetTestDatabase() { await pool.query("DROP SCHEMA IF EXISTS public CASCADE; CREATE SCHEMA public"); return pool; }
+export async function closeTestDatabase() { await pool.end(); }
+` : `import { MongoClient } from "mongodb";
 const client = new MongoClient(process.env.TEST_MONGODB_URI ?? "mongodb://localhost:27018/?replicaSet=rs0&directConnection=true");
 export async function openTestDatabase() { await client.connect(); return client.db(process.env.TEST_MONGODB_DB_NAME ?? "${options.name.replaceAll("-", "_")}_test"); }
 export async function resetTestDatabase() { const database = await openTestDatabase(); await database.dropDatabase(); return database; }
 export async function closeTestDatabase() { await client.close(); }
 `);
-add(`${svc}/docker-compose.test.yml`, `name: ${options.name}-test
+add(`${svc}/docker-compose.test.yml`, postgres ? `name: ${options.name}-test
+services:
+  postgres:
+    image: postgres:17
+    ports:
+      - "5433:5432"
+    environment:
+      POSTGRES_DB: ${databaseName}_test
+      POSTGRES_PASSWORD: postgres
+    tmpfs:
+      - /var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d ${databaseName}_test"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+` : `name: ${options.name}-test
 services:
   mongo:
     image: mongo:8
@@ -476,7 +542,12 @@ Run \`npm run validate:architecture\` and \`npm run format:check\` after changin
 if (options.ui) {
 const uiDeps = { "@tailwindcss/vite": "^4.1.18", "@vueuse/core": "^14.3.0", axios: "^1.9.0", pinia: "^3.0.1", primevue: "^4.2.5", vue: "^3.5.13", "vue-router": "^4.5.0", ...(options.auth === "firebase" ? { firebase: "^11.0.0" } : {}) };
 const uiDevDeps = { "@tsconfig/node22": "^22.0.1", "@zaaxch/tailframe": contractVersion, "@types/node": "^22.13.14", "@vitejs/plugin-vue": "^5.2.3", "@vue/test-utils": "^2.4.10", "@vue/tsconfig": "^0.7.0", jsdom: "^29.1.1", "npm-run-all2": "^7.0.2", prettier: "3.5.3", typescript: "~5.8.0", vite: "^6.2.4", vitest: "^4.1.7", "vue-tsc": "^2.2.8" };
-add(`${ui}/package.json`, JSON.stringify({ name: ui, version: "0.1.0", private: true, type: "module", scripts: { dev: "vite --host 0.0.0.0", build: "run-p type-check \"build-only {@}\" --", "build-only": "vite build", "type-check": "vue-tsc --build", test: "vitest run", "test:watch": "vitest", "validate:architecture": "tailframe validate --kind ui .", format: "prettier --write src/", "format:check": "prettier --check src/" }, dependencies: uiDeps, devDependencies: uiDevDeps }, null, "\t"));
+add(`${ui}/package.json`, JSON.stringify({ name: ui, version: "0.1.0", private: true, type: "module", scripts: { dev: "vite --host 0.0.0.0", build: "run-p type-check \"build-only {@}\" --", "build-only": "vite build", "type-check": "vue-tsc --build", test: "vitest run", "test:watch": "vitest", "validate:architecture": "tailframe validate .", "sync:architecture": "tailframe sync --check .", format: "prettier --write src/", "format:check": "prettier --check src/" }, dependencies: uiDeps, devDependencies: uiDevDeps }, null, "\t"));
+add(`${ui}/tailframe.json`, configSource({
+	kind: "ui",
+	profiles: [...(options.auth === "firebase" ? ["firebase"] : []), "notifications"],
+	contractVersion
+}));
 add(`${ui}/.prettierrc.json`, JSON.stringify(prettierConfig, null, "\t"));
 add(`${ui}/.gitattributes`, gitAttributes);
 add(`${ui}/tsconfig.json`, JSON.stringify({ files: [], references: [{ path: "./tsconfig.app.json" }, { path: "./tsconfig.node.json" }] }, null, "\t"));
@@ -515,6 +586,7 @@ export default createRouter({
 });`);
 add(`${ui}/src/platform/http.ts`, uiHttpSource);
 if (options.auth === "firebase") add(`${ui}/src/app/configureHttp.ts`, configureHttpSource);
+add(`${ui}/src/platform/config.ts`, `export const apiBaseUrl = \`\${window.location.origin}/api/v1\`;`);
 add(`${ui}/src/modules/health/api/health.api.ts`, healthApiSource);
 add(`${ui}/src/modules/health/views/HealthView.vue`, `<script setup lang="ts">
 import { ref } from "vue";
@@ -556,23 +628,31 @@ async function checkReadiness() {
 		<p v-if="error" role="alert">{{ error }}</p>
 	</main>
 </template>`);
-add(`${ui}/src/app/App.vue`, `<template><RouterView /></template><script setup lang="ts">import { RouterView } from "vue-router";</script>`);
+add(`${ui}/src/app/App.vue`, `<template>
+	<RouterView />
+	<NotificationHost />
+</template>
+
+<script setup lang="ts">
+import { RouterView } from "vue-router";
+import NotificationHost from "@/app/components/NotificationHost.vue";
+</script>`);
 add(`${ui}/src/app/startApplication.ts`, `import { createApp } from "vue";\nimport { createPinia } from "pinia";\nimport PrimeVue from "primevue/config";\nimport App from "@/app/App.vue";\n${options.auth === "firebase" ? 'import { configureHttp } from "@/app/configureHttp";\n' : ""}import router from "@/app/router";\nimport "@/app/styles.css";\nexport function startApplication() {\n\tconst app = createApp(App);\n\tconst pinia = createPinia();\n\tapp.use(pinia).use(PrimeVue).use(router);\n\t${options.auth === "firebase" ? "configureHttp(pinia);\n\t" : ""}app.mount("#app");\n}\n`);
 add(`${ui}/src/main.ts`, `import { startApplication } from "@/app/startApplication";\nstartApplication();\n`);
 add(`${ui}/src/app/styles.css`, `@import "tailwindcss";\n:root { font-family: Inter, ui-sans-serif, system-ui; color: #17221c; background: #f5f3ec; }\nbody { margin: 0; }`);
-add(`${ui}/src/app/__tests__/App.spec.ts`, `import { mount } from "@vue/test-utils";\nimport App from "@/app/App.vue";\ndescribe("App", () => { it("renders a router view", () => { expect(mount(App, { global: { stubs: ["RouterView"] } }).exists()).toBe(true); }); });`);
+add(`${ui}/src/app/__tests__/App.spec.ts`, `import { mount } from "@vue/test-utils";\nimport App from "@/app/App.vue";\ndescribe("App", () => { it("renders a router view", () => { expect(mount(App, { global: { stubs: ["RouterView", "NotificationHost"] } }).exists()).toBe(true); }); });`);
 add(`${ui}/AGENTS.md`, `# ${title} UI guidance
 
 ## Scope
 These conventions apply to \`${ui}/src\`. Inspect the nearest working module before adding files.
 
 ## Architecture vocabulary
-- Use \`src/app\` for Vue bootstrap, the application shell, routing, global styles, and the closed Tailframe auth/theme catalog.
+- Use \`src/app\` for Vue bootstrap, the application shell, routing, global styles, and the closed Tailframe auth/notification/theme catalog.
 - Use \`src/core\` only for small technology-neutral client contracts.
 - Use \`src/platform\` for Axios, Firebase, browser APIs, and other technical adapters.
 - Use \`src/modules/<module>\` for every product capability. Never substitute \`src/features\` or global \`apis\`, \`views\`, \`services\`, \`stores\`, or \`types\` directories.
-- These are the only UI architecture roots. Keep \`src/core\` flat. Shared capability code belongs to the module that owns it. \`src/app/stores\` is closed to generated \`auth.store.ts\` and \`theme.store.ts\`; \`src/app/public\` is closed to generated \`ThemeToggle.vue\`. Do not edit their implementations; only the generated theme storage key varies. Internal shell components remain private under \`src/app/components\`.
-- Never create \`src/modules/theme\` or \`src/modules/auth\`. Product records, current-user domain records, selections, filters, workflows, and module API calls always belong to the owning product module.
+- These are the only UI architecture roots. Keep \`src/core\` flat. Shared capability code belongs to the module that owns it. \`src/app/stores\` is closed to generated \`auth.store.ts\`, \`notification.store.ts\`, and \`theme.store.ts\`; \`src/app/public\` is closed to generated \`ThemeToggle.vue\`. Do not edit their implementations; only the generated theme storage key varies. Internal shell components remain private under \`src/app/components\`.
+- Never create \`src/modules/theme\`, \`src/modules/auth\`, or \`src/modules/notification\`. Product records, current-user domain records, selections, filters, workflows, and module API calls always belong to the owning product module.
 
 ## Change placement
 | Change | Canonical owner |
@@ -580,14 +660,14 @@ These conventions apply to \`${ui}/src\`. Inspect the nearest working module bef
 | Capability API, component, composable, state, type, or view | \`src/modules/<module>\` |
 | Capability intentionally consumed by another module | Named file directly under provider \`src/modules/<module>/public\` |
 | Axios, Firebase, browser, or vendor mechanism | \`src/platform\` |
-| Firebase identity/readiness or theme preference | Generated \`src/app/stores/auth.store.ts\` or \`theme.store.ts\` |
+| Firebase identity/readiness, notification queue, or theme preference | Generated \`src/app/stores/auth.store.ts\`, \`notification.store.ts\`, or \`theme.store.ts\` |
 | Canonical theme control consumed by modules | Generated \`src/app/public/ThemeToggle.vue\` |
 | Any other state or reusable presentation | Owning \`src/modules/<module>\` |
 | Shell, router, global styles, or cross-capability composition | \`src/app\` |
 | Technology-neutral client contract | Flat \`src/core\` |
 | Root executable | Bootstrap of \`src/app\` only |
 
-UI modules may import a sibling only through a named file directly under the provider's \`public/\` directory; keep the graph acyclic. From app, modules may import only generated \`auth.store.ts\`, \`theme.store.ts\`, and \`ThemeToggle.vue\`; every other app path is private. App views and shell components consume modules only through named module \`public/\` entries; route module views directly from \`app/router.ts\`. Use \`@/\` or relative internal imports; do not add another source alias. Platform imports neither app nor modules.
+UI modules may import a sibling only through a named file directly under the provider's \`public/\` directory; keep the graph acyclic. From app, modules may import only generated \`auth.store.ts\`, \`notification.store.ts\`, \`theme.store.ts\`, and \`ThemeToggle.vue\`; every other app path is private. App views and shell components consume modules only through named module \`public/\` entries; route module views directly from \`app/router.ts\`. Use \`@/\` or relative internal imports; do not add another source alias. Platform imports neither app nor modules.
 
 ## Module shape
 Under \`src/modules/<module>\`, add only needed \`api/\`, \`components/\`, \`composables/\`, \`public/\`, \`routes/\`, \`stores/\`, \`types/\`, \`views/\`, and \`__tests__/\` directories. Public entries are named direct files, never nested directories or barrels. Do not invent alternative layer names or generate speculative CRUD. Create module and public shell files only with \`tailframe generate\`.
@@ -602,7 +682,7 @@ Use named routes.${options.auth === "firebase" ? " Preserve Firebase authenticat
 
 ## State management
 Keep local state local. Use Pinia only for state shared across routes or unrelated components.
-Keep all product state in the owning module. The auth/theme stores and ThemeToggle are Tailframe-owned generated sources shared byte-for-byte across projects apart from the explicit theme storage key.
+Keep all product state in the owning module. The auth/notification/theme stores, NotificationHost, and ThemeToggle are Tailframe-owned generated sources shared byte-for-byte across projects apart from the explicit theme storage key.
 
 ## UI behavior
 Reuse Vue, PrimeVue, Tailwind, loading, error, and accessibility conventions. Provide explicit loading, empty, error, and authorization states.
@@ -852,24 +932,19 @@ docker compose --env-file "\${INFRA_ENV}" --file "\${COMPOSE_FILE}" pull
 docker compose --env-file "\${INFRA_ENV}" --file "\${COMPOSE_FILE}" up -d --wait
 `);
 
-add(`${svc}/deploy/mongo/10-create-users.js`, `const applicationPassword = process.env.MONGODB_APP_PASSWORD;
-const backupPassword = process.env.MONGODB_BACKUP_PASSWORD;
-
-if (!applicationPassword || !backupPassword) {
-	throw new Error("MONGODB_APP_PASSWORD and MONGODB_BACKUP_PASSWORD are required");
-}
-
-db.getSiblingDB("${databaseName}").createUser({
-	user: "${mongoApplicationUser}",
-	pwd: applicationPassword,
-	roles: [{ role: "readWrite", db: "${databaseName}" }]
-});
+if (postgres) add(`${svc}/deploy/postgres/10-create-application-user.sh`, `#!/usr/bin/env bash
+set -euo pipefail
 
-db.getSiblingDB("admin").createUser({
-	user: "${mongoBackupUser}",
-	pwd: backupPassword,
-	roles: [{ role: "backup", db: "admin" }]
-});
+psql --set ON_ERROR_STOP=1 --username postgres --dbname "${databaseName}" --set app_password="\${POSTGRES_APP_PASSWORD}" <<'SQL'
+SELECT 'CREATE ROLE "${options.name}-app" LOGIN PASSWORD ' || quote_literal(:'app_password')
+WHERE NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${options.name}-app')\gexec
+GRANT CONNECT ON DATABASE "${databaseName}" TO "${options.name}-app";
+GRANT USAGE ON SCHEMA public TO "${options.name}-app";
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO "${options.name}-app";
+GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO "${options.name}-app";
+ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO "${options.name}-app";
+ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO "${options.name}-app";
+SQL
 `);
 
 add(`${svc}/docs/production-deployment.md`, `# Production deployment
@@ -964,24 +1039,30 @@ const devVolumes = [
 	...(options.auth === "firebase" ? ["      - ./firebase-service-account.development.json:/app/firebase-service-account.development.json:ro"] : [])
 ];
 const productionDependencies = [
-	["mongo-init", "service_completed_successfully"],
+	["schema-init", "service_completed_successfully"],
 	...(options.redis ? [["redis", "service_healthy"]] : [])
 ];
 const developmentDependencies = [
-	["mongo-init", "service_completed_successfully"],
+	["schema-init", "service_completed_successfully"],
 	...(options.redis ? [["redis", "service_started"]] : [])
 ];
 const dependsBlock = `\n    depends_on:\n${productionDependencies.map(([dependency, condition]) => `      ${dependency}:\n        condition: ${condition}`).join("\n")}`;
 const devDependsBlock = `\n    depends_on:\n${developmentDependencies.map(([dependency, condition]) => `      ${dependency}:\n        condition: ${condition}`).join("\n")}`;
 const productionEnvironment = [
 	"      NODE_ENV: production",
-	`      MONGODB_URI: "mongodb://${mongoApplicationUser}:\${MONGODB_APP_PASSWORD:?Set MONGODB_APP_PASSWORD}@mongodb:27017/${databaseName}?replicaSet=rs0&directConnection=true&authSource=${databaseName}"`,
-	`      MONGODB_DB_NAME: "${databaseName}"`,
+	...(postgres
+		? [`      POSTGRES_URI: "postgresql://${options.name}-app:\${POSTGRES_APP_PASSWORD:?Set POSTGRES_APP_PASSWORD}@postgres:5432/${databaseName}"`]
+		: [
+			`      MONGODB_URI: "mongodb://${mongoApplicationUser}:\${MONGODB_APP_PASSWORD:?Set MONGODB_APP_PASSWORD}@mongodb:27017/${databaseName}?replicaSet=rs0&directConnection=true&authSource=${databaseName}"`,
+			`      MONGODB_DB_NAME: "${databaseName}"`
+		]),
 	...(options.auth === "firebase" ? ["      GOOGLE_APPLICATION_CREDENTIALS: /app/secrets/firebase-service-account.json"] : []),
 	...(options.redis ? ["      REDIS_URL: \"redis://:\${REDIS_PASSWORD:?Set REDIS_PASSWORD}@redis:6379\""] : [])
 ];
 const productionEnvironmentBlock = `\n    environment:\n${productionEnvironment.join("\n")}`;
-const databaseEnvironmentBlock = `\n    environment:\n      MONGODB_URI: "mongodb://mongodb:27017/?replicaSet=rs0&directConnection=true"`;
+const databaseEnvironmentBlock = postgres
+	? `\n    environment:\n      POSTGRES_URI: "postgresql://${options.name}-app:development@postgres:5432/${databaseName}"`
+	: `\n    environment:\n      MONGODB_URI: "mongodb://mongodb:27017/?replicaSet=rs0&directConnection=true"`;
 const volumeBlock = serviceVolumes.length ? `\n    volumes:\n${serviceVolumes.join("\n")}` : "";
 const workerService = options.worker ? `\n  worker:
     image: \${ECR_IMAGE:?Set ECR_IMAGE}:\${IMAGE_TAG:?Set IMAGE_TAG}
@@ -998,7 +1079,25 @@ const workerService = options.worker ? `\n  worker:
     networks:
       - backend
     restart: unless-stopped` : "";
-const databaseService = `\n  mongodb:
+const databaseService = postgres ? `\n  postgres:
+    image: postgres:17
+    environment:
+      POSTGRES_DB: "${databaseName}"
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: \${POSTGRES_ROOT_PASSWORD:?Set POSTGRES_ROOT_PASSWORD}
+      POSTGRES_APP_PASSWORD: \${POSTGRES_APP_PASSWORD:?Set POSTGRES_APP_PASSWORD}
+    volumes:
+      - \${POSTGRES_DATA_DIR:?Set POSTGRES_DATA_DIR}:/var/lib/postgresql/data
+      - ./deploy/postgres/10-create-application-user.sh:/docker-entrypoint-initdb.d/10-create-application-user.sh:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d ${databaseName}"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 20s
+    networks:
+      - backend
+    restart: unless-stopped` : `\n  mongodb:
     image: mongo:8
     command:
       - mongod
@@ -1011,8 +1110,12 @@ const databaseService = `\n  mongodb:
       MONGO_INITDB_DATABASE: "${databaseName}"
       MONGO_INITDB_ROOT_USERNAME: "${options.name}-root"
       MONGO_INITDB_ROOT_PASSWORD: \${MONGODB_ROOT_PASSWORD:?Set MONGODB_ROOT_PASSWORD}
+      MONGODB_DB_NAME: "${databaseName}"
+      MONGODB_APP_USERNAME: "${mongoApplicationUser}"
       MONGODB_APP_PASSWORD: \${MONGODB_APP_PASSWORD:?Set MONGODB_APP_PASSWORD}
+      MONGODB_BACKUP_USERNAME: "${mongoBackupUser}"
       MONGODB_BACKUP_PASSWORD: \${MONGODB_BACKUP_PASSWORD:?Set MONGODB_BACKUP_PASSWORD}
+      MONGODB_APP_COLLECTIONS: "_tailframe_reserved"
     volumes:
       - \${MONGO_DATA_DIR:?Set MONGO_DATA_DIR}:/data/db
       - \${MONGO_KEYFILE:?Set MONGO_KEYFILE}:/etc/mongo-keyfile/keyfile:ro
@@ -1059,6 +1162,17 @@ const databaseService = `\n  mongodb:
         }"
     networks:
       - backend`;
+const schemaInitDependencies = postgres ? [["postgres", "service_healthy"]] : [["mongo-init", "service_completed_successfully"]];
+const schemaInitDependsBlock = `\n    depends_on:\n${schemaInitDependencies.map(([dependency, condition]) => `      ${dependency}:\n        condition: ${condition}`).join("\n")}`;
+const schemaInitEnvironment = postgres
+	? `\n    environment:\n      POSTGRES_URI: "postgresql://postgres:\${POSTGRES_ROOT_PASSWORD:?Set POSTGRES_ROOT_PASSWORD}@postgres:5432/${databaseName}"`
+	: `\n    environment:\n      MONGODB_URI: "mongodb://${options.name}-root:\${MONGODB_ROOT_PASSWORD:?Set MONGODB_ROOT_PASSWORD}@mongodb:27017/${databaseName}?replicaSet=rs0&directConnection=true&authSource=admin"\n      MONGODB_DB_NAME: "${databaseName}"`;
+const schemaInitService = `\n  schema-init:
+    image: \${ECR_IMAGE:?Set ECR_IMAGE}:\${IMAGE_TAG:?Set IMAGE_TAG}
+    command: ["node", "dist/app/cli/applySchema.js"]${schemaInitEnvironment}${schemaInitDependsBlock}
+    networks:
+      - backend
+    restart: "no"`;
 const redisService = options.redis ? `\n  redis:
     image: redis:7-alpine
     command:
@@ -1109,7 +1223,7 @@ services:
     stop_grace_period: 2m
     networks:
       - backend
-    restart: unless-stopped${workerService}${databaseService}${redisService}
+    restart: unless-stopped${workerService}${schemaInitService}${databaseService}${redisService}
 networks:
   backend:
     driver: bridge
@@ -1124,7 +1238,21 @@ const devWorker = options.worker ? `\n  worker:
     command: ["npm", "run", "dev:worker"]${databaseEnvironmentBlock}
     volumes:
 ${devVolumes.join("\n")}${devDependsBlock}` : "";
-const devDatabase = `\n  mongodb:
+const devDatabase = postgres ? `\n  postgres:
+    image: postgres:17
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_DB: ${databaseName}
+      POSTGRES_USER: ${options.name}-app
+      POSTGRES_PASSWORD: development
+    volumes:
+      - postgres-dev-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${options.name}-app -d ${databaseName}"]
+      interval: 2s
+      timeout: 2s
+      retries: 30` : `\n  mongodb:
     image: mongo:8
     command: mongod --replSet rs0 --bind_ip_all
     ports:
@@ -1160,11 +1288,23 @@ const devRedis = options.redis ? `\n  redis:
     volumes:
       - redis-dev-data:/data` : "";
 const devNamedVolumes = [
-	"  mongodb-dev-data:",
+	postgres ? "  postgres-dev-data:" : "  mongodb-dev-data:",
 	...(options.redis ? ["  redis-dev-data:"] : [])
 ];
 add(`${svc}/docker-compose.dev.yml`, `name: ${options.name}-dev
 services:
+  schema-init:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    env_file:
+      - .env.development
+    command: ["npm", "run", "schema:apply:dev"]${databaseEnvironmentBlock}
+    volumes:
+${devVolumes.join("\n")}
+    depends_on:
+      ${postgres ? "postgres" : "mongo-init"}:
+        condition: ${postgres ? "service_healthy" : "service_completed_successfully"}
   ${options.name}:
     build:
       context: .
@@ -1179,6 +1319,16 @@ volumes:
 ${devNamedVolumes.join("\n")}
 `);
 
+for (const [relative, content] of Object.entries(ownedSources({ kind: "service", profiles: serviceProfiles }))) {
+	add(`${svc}/${relative}`, content);
+}
+if (options.ui) {
+	const uiProfiles = [...(options.auth === "firebase" ? ["firebase"] : []), "notifications"];
+	for (const [relative, content] of Object.entries(ownedSources({ kind: "ui", profiles: uiProfiles }))) {
+		add(`${ui}/${relative}`, content);
+	}
+}
+
 for (const [relative, content] of Object.entries(files)) {
 	const destination = path.join(root, relative);
 	fs.mkdirSync(path.dirname(destination), { recursive: true });
@@ -1186,5 +1336,10 @@ for (const [relative, content] of Object.entries(files)) {
 	if (relative.endsWith(".sh")) fs.chmodSync(destination, 0o755);
 }
 
-return { root, name: options.name, database: "mongo", authentication: options.auth, ui: options.ui, redis: options.redis, worker: options.worker, repositories: [svc, ...(options.ui ? [ui] : [])], files: Object.keys(files).length };
+for (const repository of [svc, ...(options.ui ? [ui] : [])]) {
+	const result = runSync(path.join(root, repository), "write", contractVersion);
+	if (result.errors.length) fail(result.errors.join("\n"));
+}
+
+return { root, name: options.name, database: options.db, authentication: options.auth, ui: options.ui, redis: options.redis, worker: options.worker, repositories: [svc, ...(options.ui ? [ui] : [])], files: Object.keys(files).length };
 }

package/src/owned-guidance.mjs

@@ -0,0 +1,15 @@
+export const OWNED_GUIDANCE_START = "<!-- tailframe:owned:start -->";
+export const OWNED_GUIDANCE_END = "<!-- tailframe:owned:end -->";
+
+export function ownedGuidance(config) {
+	const profileList = config.profiles.length ? config.profiles.join(", ") : "none";
+	const client = config.kind !== "service";
+	return `${OWNED_GUIDANCE_START}
+## Tailframe-owned contract
+
+- Contract: \`${config.contractVersion}\`; kind: \`${config.kind}\`; profiles: ${profileList}.
+- Run \`npm run sync:architecture\` and \`npm run validate:architecture\` after architectural changes.
+- Files written by \`tailframe sync --write\` are generated sources. Change their canonical templates in Tailframe, not in this product.
+- Keep product capabilities under ${client ? "`src/modules/<module>` (or `lib/modules/<module>` for Flutter)" : "`src/modules/<module>`"}; keep application assembly, technology-neutral contracts, and provider adapters in their canonical app/core/platform roots.
+${client ? "- Notifications use the Tailframe-owned application-shell queue and host. Product copy remains in the owning capability module.\n" : "- Every use case exposes `execute(context, input)`. Entry points construct a request or system context and pass an explicit input object.\n- Resident processes perform no DDL. `schema:apply` is the only schema lifecycle entry point.\n- RPC operations use `<owning-module>.<operation>` with no compatibility aliases.\n"}${OWNED_GUIDANCE_END}`;
+}