Build a Backend API - NaaP Docs

AI prompt to create a robust backend with Express, Prisma, and PostgreSQL for your NaaP plugin.

When to Use This#

Use this prompt when:

You have a frontend-only plugin and want to add a backend
You're building a full-stack plugin from scratch and need the API designed
You need to add new API endpoints to an existing backend
You want to redesign your database schema

Prompt: Create a Backend from Scratch#

Markdown

1	# Task: Create a Backend API for My NaaP Plugin
2
3	## Context
4
5	NaaP plugins can have Express.js backends with PostgreSQL databases.
6	The shell proxies frontend API calls to the plugin backend automatically.
7
8	Technical requirements:
9	- Runtime: Node.js 20+, TypeScript
10	- Framework: Express.js
11	- Database: PostgreSQL via Prisma ORM
12	- Port: Each plugin backend runs on a unique port
13	- Health check: Must expose GET /health returning { status: 'ok' }
14	- API prefix: All routes are under /api/v1/[plugin-name]/
15
16	IMPORTANT — Database Architecture:
17	NaaP uses a single PostgreSQL database with multi-schema isolation.
18	All models live in `packages/database/prisma/schema.prisma`, NOT in plugin directories.
19	See [Database Architecture Rules](/docs/concepts/database-architecture) for full details.
20
21	Database client (backend/src/db/client.ts):
22	```typescript
23	import { prisma } from '@naap/database';
24	export const db = prisma;

NEVER use new PrismaClient() or import from @prisma/client
ALWAYS import from @naap/database
Every model MUST have @@schema("plugin_<name>") annotation
Model names MUST be prefixed (e.g., MyPluginTask, not Task)

Plugin Description#

Plugin name: [YOUR_PLUGIN_NAME] Port: [PICK A PORT, e.g., 4050]

Data this plugin manages: [DESCRIBE YOUR DATA — for example:

"Projects with name, description, status, and deadline"
"Team members assigned to projects"
"Tasks within projects with priority and assignee"
"Activity log of all changes" ]

API Endpoints Needed#

[LIST YOUR ENDPOINTS — or write "Design the API for me based on the data description above"]

Example format:

GET /projects → List all projects (paginated)
POST /projects → Create a new project
GET /projects/:id → Get single project with details
PUT /projects/:id → Update a project
DELETE /projects/:id → Delete a project
GET /projects/:id/tasks → List tasks for a project
POST /projects/:id/tasks → Create a task in a project

Requirements#

Prisma models (add to packages/database/prisma/schema.prisma):
- Every model annotated with @@schema("plugin_<name>")
- Every model prefixed (e.g., MyPluginTask, not Task)
- All models with id (uuid), createdAt, updatedAt
- Proper relations between models
- Indexes on frequently queried fields
- Enum types where appropriate (also annotated with @@schema)
Express server (backend/src/server.ts):
- CORS enabled
- JSON body parsing
- Health check at /health
- Route registration
- Error handling middleware
- Graceful shutdown
Route handlers (backend/src/routes/):
- One file per resource (e.g., projects.ts, tasks.ts)
- Input validation on POST/PUT (check required fields)
- Proper HTTP status codes (200, 201, 400, 404, 500)
- Pagination on list endpoints (page, limit query params)
- Response format: { success: true, data: T, meta?: { page, limit, total } }
- Error format: { success: false, error: { code, message } }
- Try/catch with meaningful error messages
Seed data (backend/prisma/seed.ts):
- Create 5-10 sample records for each model
- Use realistic data (not "test1", "test2")
package.json:
- scripts: dev, build, start (NO db:generate, db:push, db:seed)
- dependencies: @naap/database: "workspace:*" (NOT @prisma/client)
- No prisma in devDependencies

Quality Standards#

Full TypeScript with proper types
Prisma singleton pattern
Modular route handlers
Input validation helpers
Consistent error response format
Helpful comments

Generate ALL files with complete code.

1
2	## Prompt: Add Endpoints to Existing Backend
3
4	```markdown
5	# Task: Add New API Endpoints to My NaaP Plugin Backend
6
7	## Existing Setup
8
9	Plugin name: [YOUR_PLUGIN_NAME]
10
11	Current Prisma schema:
12	[PASTE YOUR CURRENT schema.prisma HERE]
13
14	Current routes:
15	[LIST YOUR EXISTING ENDPOINTS]
16
17	## New Endpoints Needed
18
19	[DESCRIBE THE NEW FUNCTIONALITY — for example:
20	- "Add a comments system: users can comment on items, edit their own comments, and delete them"
21	- "Add a search endpoint that searches across all fields with full-text search"
22	- "Add bulk operations: bulk delete, bulk update status, bulk export as CSV"
23	- "Add an analytics endpoint that returns aggregated statistics"
24	]
25
26	## Requirements
27
28	1. Add new Prisma models if needed (show the full updated schema)
29	2. Create new route files for new resources
30	3. Update server.ts to register new routes
31	4. Add proper validation and error handling
32	5. Include pagination where appropriate
33	6. Don't modify existing endpoints unless necessary
34
35	Generate updated schema.prisma, new route files, and updated server.ts.

Prompt: Design a Database Schema#

If you're not sure how to structure your data, use this prompt first:

Markdown

1	# Task: Design a Database Schema for My NaaP Plugin
2
3	## What the Plugin Does
4
5	[DESCRIBE YOUR PLUGIN IN PLAIN LANGUAGE — for example:
6	"A recipe management app where users can:
7	- Create and organize recipes with ingredients and steps
8	- Tag recipes with categories (breakfast, lunch, dinner, dessert)
9	- Rate recipes and leave reviews
10	- Create meal plans for the week
11	- Generate shopping lists from selected recipes"
12	]
13
14	## Requirements
15
16	Design a PostgreSQL database schema using Prisma syntax that:
17
18	1. Supports all the features described above
19	2. Uses proper data types (String, Int, Float, Boolean, DateTime, Json)
20	3. Has proper relations (one-to-many, many-to-many)
21	4. Uses enums for fixed choices
22	5. Includes indexes for common queries
23	6. Every model has: id (uuid, auto-generated), createdAt, updatedAt
24	7. Uses soft deletes (deletedAt DateTime?) where appropriate
25	8. Is normalized (no duplicate data)
26
27	Output:
28	1. The complete Prisma schema
29	2. An explanation of each model and why it's structured that way
30	3. Example queries for common operations
31	4. Suggested API endpoints based on the schema
32
33	Think step by step about the data relationships before generating the schema.

After the AI Generates Code#

Terminal

# 1. Copy generated model definitions into packages/database/prisma/schema.prisma

# 2. Copy route/server files into your plugin's backend/src/ directory

# 3. Register the schema (if new)

# - Add CREATE SCHEMA to docker/init-schemas.sql

# - Add schema name to the schemas array in schema.prisma

# 4. Generate and push from the central package

$cd packages/database

$npx prisma generate

$npx prisma db push

# 5. Install plugin dependencies

$cd ../../plugins/[plugin-name]/backend

$npm install

# 6. Start the backend

$npm run dev

# 7. Test an endpoint

$curl http://localhost:4050/health

$curl http://localhost:4050/api/v1/[plugin-name]/[resource]

Important: Models go in packages/database/prisma/schema.prisma, NOT in the plugin directory. See Database Architecture for the full rules.

When to Use This#

Use this prompt when:

You have a frontend-only plugin and want to add a backend
You're building a full-stack plugin from scratch and need the API designed
You need to add new API endpoints to an existing backend
You want to redesign your database schema

Prompt: Create a Backend from Scratch#

Markdown

1	# Task: Create a Backend API for My NaaP Plugin
2
3	## Context
4
5	NaaP plugins can have Express.js backends with PostgreSQL databases.
6	The shell proxies frontend API calls to the plugin backend automatically.
7
8	Technical requirements:
9	- Runtime: Node.js 20+, TypeScript
10	- Framework: Express.js
11	- Database: PostgreSQL via Prisma ORM
12	- Port: Each plugin backend runs on a unique port
13	- Health check: Must expose GET /health returning { status: 'ok' }
14	- API prefix: All routes are under /api/v1/[plugin-name]/
15
16	IMPORTANT — Database Architecture:
17	NaaP uses a single PostgreSQL database with multi-schema isolation.
18	All models live in `packages/database/prisma/schema.prisma`, NOT in plugin directories.
19	See [Database Architecture Rules](/docs/concepts/database-architecture) for full details.
20
21	Database client (backend/src/db/client.ts):
22	```typescript
23	import { prisma } from '@naap/database';
24	export const db = prisma;

NEVER use new PrismaClient() or import from @prisma/client
ALWAYS import from @naap/database
Every model MUST have @@schema("plugin_<name>") annotation
Model names MUST be prefixed (e.g., MyPluginTask, not Task)

Plugin Description#

Plugin name: [YOUR_PLUGIN_NAME] Port: [PICK A PORT, e.g., 4050]

Data this plugin manages: [DESCRIBE YOUR DATA — for example:

"Projects with name, description, status, and deadline"
"Team members assigned to projects"
"Tasks within projects with priority and assignee"
"Activity log of all changes" ]

API Endpoints Needed#

[LIST YOUR ENDPOINTS — or write "Design the API for me based on the data description above"]

Example format:

GET /projects → List all projects (paginated)
POST /projects → Create a new project
GET /projects/:id → Get single project with details
PUT /projects/:id → Update a project
DELETE /projects/:id → Delete a project
GET /projects/:id/tasks → List tasks for a project
POST /projects/:id/tasks → Create a task in a project

Requirements#

Prisma models (add to packages/database/prisma/schema.prisma):
- Every model annotated with @@schema("plugin_<name>")
- Every model prefixed (e.g., MyPluginTask, not Task)
- All models with id (uuid), createdAt, updatedAt
- Proper relations between models
- Indexes on frequently queried fields
- Enum types where appropriate (also annotated with @@schema)
Express server (backend/src/server.ts):
- CORS enabled
- JSON body parsing
- Health check at /health
- Route registration
- Error handling middleware
- Graceful shutdown
Route handlers (backend/src/routes/):
- One file per resource (e.g., projects.ts, tasks.ts)
- Input validation on POST/PUT (check required fields)
- Proper HTTP status codes (200, 201, 400, 404, 500)
- Pagination on list endpoints (page, limit query params)
- Response format: { success: true, data: T, meta?: { page, limit, total } }
- Error format: { success: false, error: { code, message } }
- Try/catch with meaningful error messages
Seed data (backend/prisma/seed.ts):
- Create 5-10 sample records for each model
- Use realistic data (not "test1", "test2")
package.json:
- scripts: dev, build, start (NO db:generate, db:push, db:seed)
- dependencies: @naap/database: "workspace:*" (NOT @prisma/client)
- No prisma in devDependencies

Quality Standards#

Full TypeScript with proper types
Prisma singleton pattern
Modular route handlers
Input validation helpers
Consistent error response format
Helpful comments

Generate ALL files with complete code.

1
2	## Prompt: Add Endpoints to Existing Backend
3
4	```markdown
5	# Task: Add New API Endpoints to My NaaP Plugin Backend
6
7	## Existing Setup
8
9	Plugin name: [YOUR_PLUGIN_NAME]
10
11	Current Prisma schema:
12	[PASTE YOUR CURRENT schema.prisma HERE]
13
14	Current routes:
15	[LIST YOUR EXISTING ENDPOINTS]
16
17	## New Endpoints Needed
18
19	[DESCRIBE THE NEW FUNCTIONALITY — for example:
20	- "Add a comments system: users can comment on items, edit their own comments, and delete them"
21	- "Add a search endpoint that searches across all fields with full-text search"
22	- "Add bulk operations: bulk delete, bulk update status, bulk export as CSV"
23	- "Add an analytics endpoint that returns aggregated statistics"
24	]
25
26	## Requirements
27
28	1. Add new Prisma models if needed (show the full updated schema)
29	2. Create new route files for new resources
30	3. Update server.ts to register new routes
31	4. Add proper validation and error handling
32	5. Include pagination where appropriate
33	6. Don't modify existing endpoints unless necessary
34
35	Generate updated schema.prisma, new route files, and updated server.ts.

Prompt: Design a Database Schema#

If you're not sure how to structure your data, use this prompt first:

Markdown

1	# Task: Design a Database Schema for My NaaP Plugin
2
3	## What the Plugin Does
4
5	[DESCRIBE YOUR PLUGIN IN PLAIN LANGUAGE — for example:
6	"A recipe management app where users can:
7	- Create and organize recipes with ingredients and steps
8	- Tag recipes with categories (breakfast, lunch, dinner, dessert)
9	- Rate recipes and leave reviews
10	- Create meal plans for the week
11	- Generate shopping lists from selected recipes"
12	]
13
14	## Requirements
15
16	Design a PostgreSQL database schema using Prisma syntax that:
17
18	1. Supports all the features described above
19	2. Uses proper data types (String, Int, Float, Boolean, DateTime, Json)
20	3. Has proper relations (one-to-many, many-to-many)
21	4. Uses enums for fixed choices
22	5. Includes indexes for common queries
23	6. Every model has: id (uuid, auto-generated), createdAt, updatedAt
24	7. Uses soft deletes (deletedAt DateTime?) where appropriate
25	8. Is normalized (no duplicate data)
26
27	Output:
28	1. The complete Prisma schema
29	2. An explanation of each model and why it's structured that way
30	3. Example queries for common operations
31	4. Suggested API endpoints based on the schema
32
33	Think step by step about the data relationships before generating the schema.

After the AI Generates Code#

Terminal

# 1. Copy generated model definitions into packages/database/prisma/schema.prisma

# 2. Copy route/server files into your plugin's backend/src/ directory

# 3. Register the schema (if new)

# - Add CREATE SCHEMA to docker/init-schemas.sql

# - Add schema name to the schemas array in schema.prisma

# 4. Generate and push from the central package

$cd packages/database

$npx prisma generate

$npx prisma db push

# 5. Install plugin dependencies

$cd ../../plugins/[plugin-name]/backend

$npm install

# 6. Start the backend

$npm run dev

# 7. Test an endpoint

$curl http://localhost:4050/health

$curl http://localhost:4050/api/v1/[plugin-name]/[resource]

Important: Models go in packages/database/prisma/schema.prisma, NOT in the plugin directory. See Database Architecture for the full rules.