Database Architecture Compliance

AI prompt to ensure your plugin follows the mandatory single-DB multi-schema architecture.

When to Use This#

Use this prompt every time you ask an AI assistant to:

Create a new plugin with a backend
Add database models to a plugin
Modify an existing database schema
Debug database connection issues
Generate Prisma code for NaaP

This ensures the AI does not generate old-style per-plugin databases or local Prisma schemas.

Prompt: Database Architecture Rules (Copy This First)#

Paste this block before any other NaaP prompt to set the ground rules:

Markdown

1	# MANDATORY: NaaP Database Architecture Rules
2
3	## Critical Constraints (MUST follow)
4
5	NaaP uses a single PostgreSQL database with multiple PostgreSQL schemas
6	for data isolation. This is non-negotiable. Every plugin and service MUST
7	follow these rules:
8
9	### Rule 1: Single Database
10	- There is ONE PostgreSQL instance: `naap-db` on port 5432, database name: `naap`
11	- Connection string: `postgresql://postgres:postgres@localhost:5432/naap`
12	- NEVER create per-plugin database containers
13	- NEVER start a separate PostgreSQL instance for any plugin
14
15	### Rule 2: Unified Prisma Schema
16	- ALL models are defined in `packages/database/prisma/schema.prisma`
17	- NEVER create a local `prisma/schema.prisma` in any plugin backend
18	- NEVER have a `prisma/` directory inside a plugin backend
19	- The generator uses `previewFeatures = ["multiSchema"]`
20
21	### Rule 3: Schema Annotations
22	- EVERY model MUST have `@@schema("plugin_xxx")` annotation
23	- EVERY enum MUST have `@@schema("plugin_xxx")` annotation
24	- Core platform models use `@@schema("public")`
25	- Plugin models use `@@schema("plugin_<plugin_name>")`
26
27	### Rule 4: Prefixed Model Names
28	- ALL plugin models MUST be prefixed to avoid name collisions
29	- Convention: `<PluginPrefix><ModelName>`
30	- Examples: CommunityPost, WalletConnection, DaydreamSession, TrackerProject
31
32	### Rule 5: Unified Client Import
33	- ALWAYS import from `@naap/database`:
34	```typescript
35	import { prisma } from '@naap/database';

NEVER import from @prisma/client or local generated directories:
TypeScript
1 // ❌ NEVER
2 import { PrismaClient } from '@prisma/client';
3 import { PrismaClient } from '../generated/client';
4 import { PrismaClient } from './generated/prisma';
5 const prisma = new PrismaClient();

Rule 6: No Local Prisma Commands in Plugins#

Plugin package.json must NOT contain: db:generate, db:push, db:migrate, db:seed
Plugin package.json must NOT list prisma as a devDependency
All schema management runs from packages/database/

Rule 7: Plugin package.json Dependencies#

JSON

1	{
2	"dependencies": {
3	"@naap/database": "workspace:*"
4	}
5	}

NOT:

JSON

1	{
2	"dependencies": {
3	"@prisma/client": "^5.x"
4	}
5	}

Rule 8: Standard db/client.ts Pattern#

Every plugin backend that uses the database MUST have:

TypeScript

// plugins/<name>/backend/src/db/client.ts
import { prisma } from '@naap/database';
export const db = prisma;

Existing Schemas#

Schema	Prefix	Owner
public	(none)	base-svc (User, Auth, Team, RBAC)
plugin_community	Community	community plugin
plugin_wallet	Wallet	my-wallet plugin
plugin_dashboard	Dashboard	my-dashboard plugin
plugin_daydream	Daydream	daydream-video plugin
plugin_gateway	Gateway	gateway-manager plugin
plugin_capacity	Capacity	capacity-planner plugin
plugin_developer_api	DevApi	developer-api plugin

Adding a New Schema#

If you need a new schema (e.g., plugin_analytics with prefix Analytics):

Add "plugin_analytics" to the schemas array in packages/database/prisma/schema.prisma
Add CREATE SCHEMA IF NOT EXISTS plugin_analytics; to docker/init-schemas.sql
Add models with @@schema("plugin_analytics") and Analytics prefix
Run npx prisma generate && npx prisma db push from packages/database/

Now proceed with the actual task below, following ALL rules above.

1
2	## Prompt: Create a New Plugin with Database
3
4	```markdown
5	# Task: Create a NaaP Plugin Backend with Database
6
7	[Paste the MANDATORY rules block above first]
8
9	## Plugin Details
10
11	Plugin name: [YOUR_PLUGIN_NAME]
12	Schema name: plugin_[YOUR_PLUGIN_NAME]
13	Model prefix: [YourPrefix]
14	Port: [PICK A PORT, e.g., 4080]
15
16	## Data Models
17
18	[DESCRIBE YOUR DATA — for example:
19	- "Bookmarks with title, URL, description, and tags"
20	- "Bookmark folders that organize bookmarks"
21	- "Share links for making bookmark collections public"
22	]
23
24	## Generate
25
26	1. Prisma models (to add to `packages/database/prisma/schema.prisma`):
27	- Every model has: id (uuid), createdAt, updatedAt
28	- Every model has @@schema("plugin_[name]")
29	- All models prefixed with [YourPrefix]
30	- Proper relations, indexes, enums
31
32	2. The SQL line for `docker/init-schemas.sql`:
33	- CREATE SCHEMA IF NOT EXISTS plugin_[name];
34
35	3. Plugin backend files:
36	- `backend/src/db/client.ts` → import from @naap/database only
37	- `backend/src/server.ts` → Express routes
38	- `backend/src/routes/*.ts` → CRUD handlers
39	- `backend/package.json` → with @naap/database dependency (NOT @prisma/client)
40
41	4. Verify checklist:
42	- ✅ No `prisma/` directory in the plugin
43	- ✅ No `@prisma/client` dependency
44	- ✅ No `new PrismaClient()` anywhere
45	- ✅ All models have @@schema() annotation
46	- ✅ All model names are prefixed
47	- ✅ .env points to postgresql://postgres:postgres@localhost:5432/naap

Prompt: Add Models to Existing Plugin#

Markdown

1	# Task: Add Database Models to an Existing NaaP Plugin
2
3	[Paste the MANDATORY rules block above first]
4
5	## Existing Plugin
6
7	Plugin name: [YOUR_PLUGIN_NAME]
8	Schema: plugin_[YOUR_PLUGIN_NAME]
9	Prefix: [YourPrefix]
10
11	Current models (already in packages/database/prisma/schema.prisma):
12	[LIST YOUR CURRENT MODELS]
13
14	## New Models Needed
15
16	[DESCRIBE THE NEW DATA — for example:
17	- "Comments on existing TrackerTask records"
18	- "Activity log tracking all changes to projects and tasks"
19	- "Labels/tags that can be applied to tasks (many-to-many)"
20	]
21
22	## Generate
23
24	1. New Prisma models to APPEND to `packages/database/prisma/schema.prisma`
25	2. Relations to existing models (if any)
26	3. Updated route handlers to use the new models
27	4. All models use @@schema("plugin_[name]") and [Prefix] naming
28
29	## After Implementation
30
31	```bash
32	cd packages/database
33	npx prisma generate
34	npx prisma db push

1
2	## Prompt: Audit Existing Plugin for Compliance
3
4	```markdown
5	# Task: Audit NaaP Plugin for Database Architecture Compliance
6
7	[Paste the MANDATORY rules block above first]
8
9	## Plugin to Audit
10
11	[PASTE YOUR PLUGIN'S FILE TREE AND KEY FILES]
12
13	## Check For
14
15	1. ❌ Any `prisma/` directory in the plugin backend
16	2. ❌ Any `import` from `@prisma/client` or local `generated/` directories
17	3. ❌ Any `new PrismaClient()` calls
18	4. ❌ Any `db:generate`, `db:push`, `db:migrate` scripts in package.json
19	5. ❌ Any `prisma` in devDependencies
20	6. ❌ Any models WITHOUT `@@schema()` annotation
21	7. ❌ Any unprefixed model names that could collide
22	8. ❌ Any `.env` pointing to a database other than `naap` on port 5432
23	9. ❌ Any Docker container definitions for per-plugin databases
24
25	## Output
26
27	For each violation found:
28	1. The file and line number
29	2. What's wrong
30	3. The exact fix (show before/after)

Quick Reference Card#

Do This	Not This
`import { prisma } from '@naap/database'`	`import { PrismaClient } from '@prisma/client'`
`"@naap/database": "workspace:*"`	`"@prisma/client": "^5.x"`
`@@schema("plugin_myapp")`	(no schema annotation)
`MyAppProject`	`Project`
Models in `packages/database/prisma/schema.prisma`	Models in `plugins/myapp/backend/prisma/schema.prisma`
`bin/db-setup.sh` or `cd packages/database && npx prisma db push`	`cd plugins/myapp/backend && npx prisma db push`
`DATABASE_URL=...localhost:5432/naap`	`DATABASE_URL=...localhost:5433/myapp_db`

When to Use This#

Use this prompt every time you ask an AI assistant to:

Create a new plugin with a backend
Add database models to a plugin
Modify an existing database schema
Debug database connection issues
Generate Prisma code for NaaP

This ensures the AI does not generate old-style per-plugin databases or local Prisma schemas.

Prompt: Database Architecture Rules (Copy This First)#

Paste this block before any other NaaP prompt to set the ground rules:

Markdown

1	# MANDATORY: NaaP Database Architecture Rules
2
3	## Critical Constraints (MUST follow)
4
5	NaaP uses a single PostgreSQL database with multiple PostgreSQL schemas
6	for data isolation. This is non-negotiable. Every plugin and service MUST
7	follow these rules:
8
9	### Rule 1: Single Database
10	- There is ONE PostgreSQL instance: `naap-db` on port 5432, database name: `naap`
11	- Connection string: `postgresql://postgres:postgres@localhost:5432/naap`
12	- NEVER create per-plugin database containers
13	- NEVER start a separate PostgreSQL instance for any plugin
14
15	### Rule 2: Unified Prisma Schema
16	- ALL models are defined in `packages/database/prisma/schema.prisma`
17	- NEVER create a local `prisma/schema.prisma` in any plugin backend
18	- NEVER have a `prisma/` directory inside a plugin backend
19	- The generator uses `previewFeatures = ["multiSchema"]`
20
21	### Rule 3: Schema Annotations
22	- EVERY model MUST have `@@schema("plugin_xxx")` annotation
23	- EVERY enum MUST have `@@schema("plugin_xxx")` annotation
24	- Core platform models use `@@schema("public")`
25	- Plugin models use `@@schema("plugin_<plugin_name>")`
26
27	### Rule 4: Prefixed Model Names
28	- ALL plugin models MUST be prefixed to avoid name collisions
29	- Convention: `<PluginPrefix><ModelName>`
30	- Examples: CommunityPost, WalletConnection, DaydreamSession, TrackerProject
31
32	### Rule 5: Unified Client Import
33	- ALWAYS import from `@naap/database`:
34	```typescript
35	import { prisma } from '@naap/database';

NEVER import from @prisma/client or local generated directories:
TypeScript
1 // ❌ NEVER
2 import { PrismaClient } from '@prisma/client';
3 import { PrismaClient } from '../generated/client';
4 import { PrismaClient } from './generated/prisma';
5 const prisma = new PrismaClient();

Rule 6: No Local Prisma Commands in Plugins#

Plugin package.json must NOT contain: db:generate, db:push, db:migrate, db:seed
Plugin package.json must NOT list prisma as a devDependency
All schema management runs from packages/database/

Rule 7: Plugin package.json Dependencies#

JSON

1	{
2	"dependencies": {
3	"@naap/database": "workspace:*"
4	}
5	}

NOT:

JSON

1	{
2	"dependencies": {
3	"@prisma/client": "^5.x"
4	}
5	}

Rule 8: Standard db/client.ts Pattern#

Every plugin backend that uses the database MUST have:

TypeScript

// plugins/<name>/backend/src/db/client.ts
import { prisma } from '@naap/database';
export const db = prisma;

Existing Schemas#

Schema	Prefix	Owner
public	(none)	base-svc (User, Auth, Team, RBAC)
plugin_community	Community	community plugin
plugin_wallet	Wallet	my-wallet plugin
plugin_dashboard	Dashboard	my-dashboard plugin
plugin_daydream	Daydream	daydream-video plugin
plugin_gateway	Gateway	gateway-manager plugin
plugin_capacity	Capacity	capacity-planner plugin
plugin_developer_api	DevApi	developer-api plugin

Adding a New Schema#

If you need a new schema (e.g., plugin_analytics with prefix Analytics):

Add "plugin_analytics" to the schemas array in packages/database/prisma/schema.prisma
Add CREATE SCHEMA IF NOT EXISTS plugin_analytics; to docker/init-schemas.sql
Add models with @@schema("plugin_analytics") and Analytics prefix
Run npx prisma generate && npx prisma db push from packages/database/

Now proceed with the actual task below, following ALL rules above.

1
2	## Prompt: Create a New Plugin with Database
3
4	```markdown
5	# Task: Create a NaaP Plugin Backend with Database
6
7	[Paste the MANDATORY rules block above first]
8
9	## Plugin Details
10
11	Plugin name: [YOUR_PLUGIN_NAME]
12	Schema name: plugin_[YOUR_PLUGIN_NAME]
13	Model prefix: [YourPrefix]
14	Port: [PICK A PORT, e.g., 4080]
15
16	## Data Models
17
18	[DESCRIBE YOUR DATA — for example:
19	- "Bookmarks with title, URL, description, and tags"
20	- "Bookmark folders that organize bookmarks"
21	- "Share links for making bookmark collections public"
22	]
23
24	## Generate
25
26	1. Prisma models (to add to `packages/database/prisma/schema.prisma`):
27	- Every model has: id (uuid), createdAt, updatedAt
28	- Every model has @@schema("plugin_[name]")
29	- All models prefixed with [YourPrefix]
30	- Proper relations, indexes, enums
31
32	2. The SQL line for `docker/init-schemas.sql`:
33	- CREATE SCHEMA IF NOT EXISTS plugin_[name];
34
35	3. Plugin backend files:
36	- `backend/src/db/client.ts` → import from @naap/database only
37	- `backend/src/server.ts` → Express routes
38	- `backend/src/routes/*.ts` → CRUD handlers
39	- `backend/package.json` → with @naap/database dependency (NOT @prisma/client)
40
41	4. Verify checklist:
42	- ✅ No `prisma/` directory in the plugin
43	- ✅ No `@prisma/client` dependency
44	- ✅ No `new PrismaClient()` anywhere
45	- ✅ All models have @@schema() annotation
46	- ✅ All model names are prefixed
47	- ✅ .env points to postgresql://postgres:postgres@localhost:5432/naap

Prompt: Add Models to Existing Plugin#

Markdown

1	# Task: Add Database Models to an Existing NaaP Plugin
2
3	[Paste the MANDATORY rules block above first]
4
5	## Existing Plugin
6
7	Plugin name: [YOUR_PLUGIN_NAME]
8	Schema: plugin_[YOUR_PLUGIN_NAME]
9	Prefix: [YourPrefix]
10
11	Current models (already in packages/database/prisma/schema.prisma):
12	[LIST YOUR CURRENT MODELS]
13
14	## New Models Needed
15
16	[DESCRIBE THE NEW DATA — for example:
17	- "Comments on existing TrackerTask records"
18	- "Activity log tracking all changes to projects and tasks"
19	- "Labels/tags that can be applied to tasks (many-to-many)"
20	]
21
22	## Generate
23
24	1. New Prisma models to APPEND to `packages/database/prisma/schema.prisma`
25	2. Relations to existing models (if any)
26	3. Updated route handlers to use the new models
27	4. All models use @@schema("plugin_[name]") and [Prefix] naming
28
29	## After Implementation
30
31	```bash
32	cd packages/database
33	npx prisma generate
34	npx prisma db push

1
2	## Prompt: Audit Existing Plugin for Compliance
3
4	```markdown
5	# Task: Audit NaaP Plugin for Database Architecture Compliance
6
7	[Paste the MANDATORY rules block above first]
8
9	## Plugin to Audit
10
11	[PASTE YOUR PLUGIN'S FILE TREE AND KEY FILES]
12
13	## Check For
14
15	1. ❌ Any `prisma/` directory in the plugin backend
16	2. ❌ Any `import` from `@prisma/client` or local `generated/` directories
17	3. ❌ Any `new PrismaClient()` calls
18	4. ❌ Any `db:generate`, `db:push`, `db:migrate` scripts in package.json
19	5. ❌ Any `prisma` in devDependencies
20	6. ❌ Any models WITHOUT `@@schema()` annotation
21	7. ❌ Any unprefixed model names that could collide
22	8. ❌ Any `.env` pointing to a database other than `naap` on port 5432
23	9. ❌ Any Docker container definitions for per-plugin databases
24
25	## Output
26
27	For each violation found:
28	1. The file and line number
29	2. What's wrong
30	3. The exact fix (show before/after)

Quick Reference Card#

Do This	Not This
`import { prisma } from '@naap/database'`	`import { PrismaClient } from '@prisma/client'`
`"@naap/database": "workspace:*"`	`"@prisma/client": "^5.x"`
`@@schema("plugin_myapp")`	(no schema annotation)
`MyAppProject`	`Project`
Models in `packages/database/prisma/schema.prisma`	Models in `plugins/myapp/backend/prisma/schema.prisma`
`bin/db-setup.sh` or `cd packages/database && npx prisma db push`	`cd plugins/myapp/backend && npx prisma db push`
`DATABASE_URL=...localhost:5432/naap`	`DATABASE_URL=...localhost:5433/myapp_db`

When to Use This#

Prompt: Database Architecture Rules (Copy This First)#

Rule 6: No Local Prisma Commands in Plugins#

Rule 7: Plugin package.json Dependencies#

Rule 8: Standard db/client.ts Pattern#

Existing Schemas#

Adding a New Schema#

Prompt: Add Models to Existing Plugin#

Quick Reference Card#

See Also#

Database Architecture Compliance

When to Use This#

Prompt: Database Architecture Rules (Copy This First)#

Rule 6: No Local Prisma Commands in Plugins#

Rule 7: Plugin package.json Dependencies#

Rule 8: Standard db/client.ts Pattern#

Existing Schemas#

Adding a New Schema#

Prompt: Add Models to Existing Plugin#

Quick Reference Card#

See Also#

1	// ❌ NEVER
2	import { PrismaClient } from '@prisma/client';
3	import { PrismaClient } from '../generated/client';
4	import { PrismaClient } from './generated/prisma';
5	const prisma = new PrismaClient();