Project Structure - NaaP Docs

Monorepo Overview#

NaaP uses an Nx monorepo with the following top-level directories:

1	NaaP/
2	├── apps/ # Applications
3	│ └── web-next/ # Main Next.js shell application
4	│
5	├── packages/ # Shared packages
6	│ ├── database/ # Unified Prisma schema (single DB, multi-schema)
7	│ ├── plugin-sdk/ # Plugin SDK (hooks, types, CLI)
8	│ ├── plugin-build/ # Plugin build tooling (createPluginConfig)
9	│ ├── types/ # Shared TypeScript types
10	│ ├── ui/ # Shared UI components
11	│ ├── theme/ # Design tokens & Tailwind config
12	│ ├── cache/ # Redis caching + rate limiting
13	│ └── ...
14	│
15	├── plugins/ # Plugin implementations
16	│ ├── __template__/ # Plugin template (scaffolding source)
17	│ ├── my-dashboard/ # Dashboard plugin
18	│ ├── gateway-manager/ # Gateway management plugin
19	│ ├── marketplace/ # Plugin marketplace
20	│ └── ...
21	│
22	├── services/ # Backend microservices
23	│ ├── base-svc/ # Core service (auth, RBAC, plugins)
24	│ ├── plugin-server/ # Plugin asset server & registry
25	│ └── ...
26	│
27	├── docs/ # Platform documentation (source)
28	├── examples/ # Example plugins
29	├── bin/ # Shell scripts (start/stop)
30	├── scripts/ # Utility & migration scripts
31	└── nginx/ # Nginx configuration

Shell Application (`apps/web-next/`)#

The shell is the host application built with Next.js 15 (App Router):

1	apps/web-next/src/
2	├── app/ # Next.js App Router
3	│ ├── (auth)/ # Auth pages (login, register, etc.)
4	│ ├── (dashboard)/ # Protected dashboard pages
5	│ ├── docs/ # Documentation site
6	│ ├── api/ # API routes
7	│ └── page.tsx # Landing page
8	│
9	├── components/
10	│ ├── layout/ # Shell layout (sidebar, top-bar)
11	│ ├── plugin/ # Plugin loader
12	│ └── ui/ # Shell-specific UI components
13	│
14	├── contexts/ # React contexts
15	│ ├── auth-context.tsx # Authentication state
16	│ ├── shell-context.tsx # Shell services (events, theme, etc.)
17	│ └── plugin-context.tsx # Plugin registry
18	│
19	├── lib/ # Utilities
20	│ ├── plugins/ # Plugin loading (UMD loader, CDN)
21	│ └── api/ # API client utilities
22	│
23	└── middleware.ts # Auth & routing middleware

Plugin Structure#

Each plugin follows a consistent structure:

1	plugins/my-plugin/
2	├── plugin.json # Plugin manifest (identity, routes, config)
3	│
4	├── frontend/
5	│ ├── src/
6	│ │ ├── App.tsx # Root component
7	│ │ ├── mount.tsx # Shell mount/unmount functions
8	│ │ └── pages/ # Plugin pages
9	│ ├── vite.config.ts # UMD build configuration (createPluginConfig)
10	│ ├── tsconfig.json
11	│ └── package.json
12	│
13	├── backend/
14	│ ├── src/
15	│ │ ├── server.ts # Express entry point
16	│ │ └── routes/ # API route handlers
17	│ ├── prisma/
18	│ │ ├── schema.prisma # Database schema
19	│ │ └── seed.ts # Seed data
20	│ └── package.json
21	│
22	└── docs/ # Plugin-specific documentation
23	└── CHANGELOG.md

Key Configuration Files#

`plugin.json` - Plugin Manifest#

Every plugin must have a plugin.json that defines its identity and capabilities:

JSON

1	{
2	"name": "my-plugin",
3	"displayName": "My Plugin",
4	"version": "1.0.0",
5	"description": "Description of what the plugin does",
6	"category": "monitoring",
7	"frontend": {
8	"entry": "./frontend/dist/production/my-plugin.js",
9	"devPort": 3010,
10	"routes": ["/my-plugin", "/my-plugin/*"]
11	},
12	"backend": {
13	"entry": "./backend/dist/server.js",
14	"devPort": 4010,
15	"apiPrefix": "/api/v1/my-plugin",
16	"healthCheck": "/healthz"
17	}
18	}

Port Single Source of Truth: plugin.json → backend.devPort is the authoritative port for each plugin's backend in local development. The PLUGIN_PORTS map in packages/plugin-sdk/src/config/ports.ts must mirror the values in plugin.json. When adding or changing a port, update plugin.json first, then sync ports.ts to match.

Plugin Discovery#

The shared utility at packages/database/src/plugin-discovery.ts scans all plugins/*/plugin.json manifests and is used by:

prisma/seed.ts — registers plugins in the database during local development
bin/sync-plugin-registry.ts — syncs the plugin registry during Vercel builds

This ensures both local dev and production environments share the same discovery logic and stay in sync.

`nx.json` - Workspace Configuration#

Nx manages build caching, task orchestration, and project dependencies across the monorepo.

`package.json` - Root Dependencies#

The root package.json contains shared development dependencies and workspace scripts.

Package Dependencies#

1	@naap/plugin-sdk ──── Used by plugins (hooks, types, CLI)
2	@naap/plugin-build ─── Used by plugins (Vite build config)
3	@naap/types ────────── Used everywhere (shared TypeScript types)
4	@naap/ui ───────────── Used by shell + plugins (shared components)
5	@naap/theme ────────── Used by shell + plugins (design tokens)
6	@naap/utils ────────── Used by shell + services (utilities)