@totaland/create-starter-kit 1.0.0 → 2.0.1

package/templates/backend/Project_Folders_Structure_Blueprint.md

@@ -0,0 +1,529 @@
+# Cybermate API - Project Folder Structure Blueprint
+
+> **Auto-detected Project Type:** Node.js/TypeScript Backend API  
+> **Framework:** Ultimate Express (Express-based)  
+> **Architecture:** Feature-based modular architecture  
+> **Monorepo:** No  
+> **Microservices:** No  
+> **Last Updated:** November 25, 2025
+
+---
+
+## 1. Structural Overview
+
+### Detected Technology Stack
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| TypeScript | ^5.8.3 | Primary language |
+| Ultimate Express | ^2.0.12 | Web framework |
+| Drizzle ORM | ^0.44.7 | Database ORM (PostgreSQL) |
+| Zod | ^4.1.12 | Schema validation |
+| Vitest | ^4.0.13 | Unit testing |
+| Playwright | - | E2E testing |
+| Biome | 2.0.6 | Linting & formatting |
+| SWC | ^1.10.1 | TypeScript compilation |
+| pnpm | - | Package manager |
+
+### Architectural Approach
+
+The project follows a **feature-based modular architecture** with clear separation of concerns:
+
+1. **Feature Modules**: Self-contained feature folders under `src/features/` that encapsulate routes, controllers, schemas, and tests
+2. **Shared Libraries**: Common utilities and infrastructure in `src/lib/`
+3. **Configuration as Code**: All configuration files at the root level
+4. **Co-located Tests**: Test files placed alongside source files (`*.test.ts`)
+5. **OpenAPI-First Design**: Zod schemas registered with OpenAPI for auto-generated documentation
+
+### Organizational Principles
+
+- **Vertical Slicing**: Features are organized by domain (health, orders) rather than technical layers
+- **Colocation**: Related files (controller, schemas, tests) live together
+- **Single Responsibility**: Each file has one clear purpose
+- **Explicit Dependencies**: All imports use explicit `.js` extensions for ESM compatibility
+
+---
+
+## 2. Directory Visualization
+
+```
+cybermate-api/
+├── .github/                          # GitHub-specific configurations
+│   ├── agents/                       # Custom AI agents (22 files)
+│   ├── instructions/                 # Copilot instruction files (12 files)
+│   └── prompts/                      # Reusable prompt templates (44 files)
+├── .vscode/                          # VS Code workspace settings
+│   └── mcp.json                      # MCP server configuration
+├── build/                            # [GENERATED] Compiled JavaScript output
+│   ├── index.js                      # Compiled entry point
+│   ├── features/                     # Compiled feature modules
+│   │   ├── health/
+│   │   └── orders/
+│   └── lib/                          # Compiled shared libraries
+├── coverage/                         # [GENERATED] Test coverage reports
+│   ├── index.html                    # Coverage dashboard
+│   ├── features/                     # Feature-specific coverage
+│   └── lib/                          # Library coverage
+├── src/                              # Source code root
+│   ├── index.ts                      # Application entry point
+│   ├── features/                     # Feature modules
+│   │   ├── health/                   # Health check feature
+│   │   │   ├── index.ts              # Router definition
+│   │   │   ├── controller.ts         # Request handlers
+│   │   │   ├── schemas.ts            # Zod schemas + OpenAPI registration
+│   │   │   └── health.test.ts        # Unit tests
+│   │   └── orders/                   # Orders feature
+│   │       ├── index.ts              # Router definition
+│   │       ├── controller.ts         # Request handlers
+│   │       └── schemas.ts            # Zod schemas + OpenAPI registration
+│   └── lib/                          # Shared utilities
+│       ├── openapi.ts                # OpenAPI registry & generator
+│       ├── validateRequest.ts        # Request validation middleware
+│       └── validateRequest.test.ts   # Middleware tests
+├── biome.json                        # Biome linter/formatter config
+├── drizzle.config.ts                 # Drizzle ORM configuration
+├── knip.json                         # Unused code detection config
+├── package.json                      # Project manifest & scripts
+├── playwright.config.ts              # Playwright E2E test config
+├── pnpm-lock.yaml                    # Dependency lock file
+├── pnpm-workspace.yaml               # pnpm workspace config
+├── tsconfig.build.json               # TypeScript build config
+├── tsconfig.json                     # TypeScript config
+├── vitest.config.ts                  # Vitest test runner config
+└── README.md                         # Project documentation
+```
+
+---
+
+## 3. Key Directory Analysis
+
+### `src/` - Source Code Root
+
+The main source directory containing all application code.
+
+| Subdirectory | Purpose | Contents |
+|--------------|---------|----------|
+| `features/` | Domain feature modules | Self-contained feature implementations |
+| `lib/` | Shared utilities | Reusable middleware, helpers, OpenAPI setup |
+
+### `src/features/` - Feature Modules
+
+Each feature is a self-contained module following a consistent internal structure:
+
+```
+features/{feature-name}/
+├── index.ts              # Router definition and route mounting
+├── controller.ts         # HTTP request handlers (thin layer)
+├── schemas.ts            # Zod validation schemas + OpenAPI registration
+├── service.ts            # [Optional] Business logic
+├── repository.ts         # [Optional] Database access layer
+├── types.ts              # [Optional] TypeScript type definitions
+└── {feature}.test.ts     # Unit tests (co-located)
+```
+
+#### Feature Module Responsibilities
+
+| File | Responsibility | Dependencies |
+|------|----------------|--------------|
+| `index.ts` | Export router, wire up routes to handlers | controller, schemas |
+| `controller.ts` | Handle HTTP request/response, delegate to services | service (optional), types |
+| `schemas.ts` | Define and export Zod schemas, register OpenAPI paths | lib/openapi |
+| `service.ts` | Business logic, orchestration | repository (optional) |
+| `repository.ts` | Database operations via Drizzle ORM | drizzle schema |
+| `*.test.ts` | Unit tests for the feature | vitest, feature modules |
+
+### `src/lib/` - Shared Libraries
+
+Contains cross-cutting utilities used by multiple features:
+
+| File | Purpose | Used By |
+|------|---------|---------|
+| `openapi.ts` | OpenAPI registry and document generator | All feature schemas, index.ts |
+| `validateRequest.ts` | Express middleware for Zod-based validation | Feature routers |
+
+### `.github/` - GitHub & AI Configuration
+
+```
+.github/
+├── agents/           # Custom GitHub Copilot agents
+├── instructions/     # Copilot instruction files (.instructions.md)
+└── prompts/          # Reusable prompt templates (.prompt.md)
+```
+
+| Subdirectory | File Pattern | Purpose |
+|--------------|--------------|---------|
+| `agents/` | `*.agent.md` | AI agent personas for specific tasks |
+| `instructions/` | `*.instructions.md` | Coding guidelines and rules |
+| `prompts/` | `*.prompt.md` | Reusable prompt templates |
+
+### `build/` - Compiled Output
+
+**[AUTO-GENERATED]** - Do not manually edit.
+
+Contains JavaScript files compiled by SWC from TypeScript sources. Mirrors the `src/` structure.
+
+### `coverage/` - Test Coverage Reports
+
+**[AUTO-GENERATED]** - Do not manually edit.
+
+Contains HTML and JSON coverage reports generated by Vitest with V8 coverage provider.
+
+---
+
+## 4. File Placement Patterns
+
+### Configuration Files
+
+| File Type | Location | Example |
+|-----------|----------|---------|
+| TypeScript config | Root | `tsconfig.json`, `tsconfig.build.json` |
+| Build tools | Root | `biome.json`, `vitest.config.ts` |
+| Database config | Root | `drizzle.config.ts` |
+| Test config | Root | `playwright.config.ts`, `vitest.config.ts` |
+| Environment | Root | `.env`, `.env.example` |
+| Package manifest | Root | `package.json` |
+
+### Source Code
+
+| File Type | Location Pattern | Example |
+|-----------|------------------|---------|
+| Feature router | `src/features/{name}/index.ts` | `src/features/orders/index.ts` |
+| Controllers | `src/features/{name}/controller.ts` | `src/features/orders/controller.ts` |
+| Schemas | `src/features/{name}/schemas.ts` | `src/features/orders/schemas.ts` |
+| Shared utilities | `src/lib/*.ts` | `src/lib/validateRequest.ts` |
+| App entry | `src/index.ts` | `src/index.ts` |
+
+### Test Files
+
+| Test Type | Location Pattern | Example |
+|-----------|------------------|---------|
+| Unit tests | Co-located with source: `*.test.ts` | `src/features/health/health.test.ts` |
+| Library tests | `src/lib/*.test.ts` | `src/lib/validateRequest.test.ts` |
+| E2E tests | `src/generated/tests/` | Playwright-generated tests |
+
+### Documentation
+
+| Doc Type | Location | Example |
+|----------|----------|---------|
+| Project README | Root | `README.md` |
+| AI instructions | `.github/instructions/` | `security-and-owasp.instructions.md` |
+| AI prompts | `.github/prompts/` | `create-specification.prompt.md` |
+
+---
+
+## 5. Naming and Organization Conventions
+
+### File Naming Patterns
+
+| Type | Convention | Examples |
+|------|------------|----------|
+| Feature folders | `lowercase-hyphenated` | `user-management/`, `orders/` |
+| TypeScript files | `lowercase-hyphenated.ts` | `controller.ts`, `validate-request.ts` |
+| Test files | `{name}.test.ts` | `health.test.ts`, `validateRequest.test.ts` |
+| Config files | `{tool}.config.ts` | `vitest.config.ts`, `drizzle.config.ts` |
+| JSON configs | `{tool}.json` | `biome.json`, `tsconfig.json` |
+
+### Code Naming Conventions
+
+| Type | Convention | Examples |
+|------|------------|----------|
+| Types/Interfaces | PascalCase | `Order`, `CreateOrderInput`, `ValidatedRequest` |
+| Zod Schemas | PascalCase + `Schema` suffix | `OrderSchema`, `CreateOrderSchema` |
+| Functions | camelCase | `getOrders`, `createOrder`, `validateRequest` |
+| Router exports | camelCase + `Router` suffix | `ordersRouter`, `healthRouter` |
+| Constants | UPPER_SNAKE_CASE | `PORT`, `DATABASE_URL` |
+| Environment vars | UPPER_SNAKE_CASE | `process.env.PORT` |
+
+### Import Conventions
+
+```typescript
+// External packages first
+import { Router } from 'ultimate-express';
+import { z } from 'zod';
+
+// Internal imports with .js extension (ESM requirement)
+import { validateRequest } from '../../lib/validateRequest.js';
+import { CreateOrderSchema } from './schemas.js';
+```
+
+### Export Conventions
+
+- **Named exports** preferred over default exports
+- **Routers** exported from feature `index.ts`
+- **Schemas** exported from `schemas.ts` for reuse
+
+---
+
+## 6. Navigation and Development Workflow
+
+### Entry Points
+
+| Purpose | File | Description |
+|---------|------|-------------|
+| Application start | `src/index.ts` | Express app setup, middleware, route mounting |
+| Feature discovery | `src/features/` | Browse available features |
+| API documentation | `/api/docs` | Scalar-powered OpenAPI docs |
+| OpenAPI spec | `/openapi.json` | Raw OpenAPI JSON |
+
+### Common Development Tasks
+
+#### Adding a New Feature
+
+1. Create feature directory: `src/features/{feature-name}/`
+2. Create required files:
+   ```
+   src/features/{feature-name}/
+   ├── index.ts        # Router
+   ├── controller.ts   # Handlers
+   ├── schemas.ts      # Validation + OpenAPI
+   └── {feature}.test.ts  # Tests
+   ```
+3. Mount router in `src/index.ts`:
+   ```typescript
+   import { featureRouter } from './features/{feature-name}/index.js';
+   app.use('/api/{feature-name}', featureRouter);
+   ```
+
+#### Adding a New Endpoint
+
+1. Define schema in `schemas.ts` with OpenAPI registration
+2. Add handler in `controller.ts`
+3. Wire route in `index.ts`
+4. Add unit test in `{feature}.test.ts`
+
+#### Adding Shared Utility
+
+1. Create file in `src/lib/{utility-name}.ts`
+2. Add tests in `src/lib/{utility-name}.test.ts`
+3. Import in features as needed
+
+### Dependency Flow
+
+```
+src/index.ts
+    ↓
+src/features/{feature}/index.ts (Router)
+    ↓
+src/features/{feature}/controller.ts (Handlers)
+    ↓
+src/features/{feature}/schemas.ts (Validation)
+    ↓
+src/lib/openapi.ts (Registry)
+src/lib/validateRequest.ts (Middleware)
+```
+
+---
+
+## 7. Build and Output Organization
+
+### Build Configuration
+
+| Tool | Config File | Purpose |
+|------|-------------|---------|
+| SWC | Via CLI in `package.json` | TypeScript → JavaScript compilation |
+| TypeScript | `tsconfig.json` | Type checking configuration |
+| Biome | `biome.json` | Linting and formatting |
+
+### NPM Scripts
+
+| Script | Command | Purpose |
+|--------|---------|---------|
+| `dev` | `vite-node --watch src/index.ts` | Development server with hot reload |
+| `build` | `swc src -d build --strip-leading-paths --copy-files` | Production build |
+| `start` | `node build/index.js` | Run production server |
+| `test` | `vitest run` | Run unit tests |
+| `test:coverage` | `vitest run --coverage` | Run tests with coverage |
+| `typecheck` | `npx tsc --noEmit` | Type checking without emit |
+
+### Output Structure
+
+```
+build/                    # Compiled JavaScript (mirrors src/)
+├── index.js
+├── features/
+│   ├── health/
+│   │   ├── index.js
+│   │   ├── controller.js
+│   │   └── schemas.js
+│   └── orders/
+│       └── ...
+└── lib/
+    ├── openapi.js
+    └── validateRequest.js
+```
+
+---
+
+## 8. Node.js-Specific Structure Patterns
+
+### Module Organization
+
+- **ESM (ES Modules)**: Project uses `"type": "module"` in package.json
+- **Import Extensions**: All local imports use `.js` extension for ESM compatibility
+- **Path Aliases**: `@/` alias available via Vitest config
+
+### Script Organization
+
+| Category | Scripts |
+|----------|---------|
+| Development | `dev`, `build`, `build:debug` |
+| Testing | `test`, `test:coverage`, `test:watch`, `test:ui` |
+| Database | `db:generate`, `db:migrate`, `db:push`, `db:studio` |
+| Quality | `typecheck`, `knip` |
+
+### Configuration Management
+
+| Config Type | File | Environment Override |
+|-------------|------|---------------------|
+| Server port | `.env` | `PORT` |
+| Database URL | `.env` | `DATABASE_URL` |
+| Test base URL | `.env` | `PLAYWRIGHT_BASE_URL` |
+
+---
+
+## 9. Extension and Evolution
+
+### Adding New Feature Module
+
+```
+src/features/{new-feature}/
+├── index.ts              # Required: Router setup
+├── controller.ts         # Required: HTTP handlers
+├── schemas.ts            # Required: Zod schemas + OpenAPI
+├── {new-feature}.test.ts # Required: Unit tests
+├── service.ts            # Optional: Business logic
+├── repository.ts         # Optional: Database access
+└── types.ts              # Optional: TypeScript types
+```
+
+### Scalability Patterns
+
+- **Feature splitting**: Large features can be split into sub-features
+- **Service extraction**: Business logic can move to dedicated service files
+- **Repository pattern**: Database operations isolated in repository files
+
+### Future Infrastructure (Planned)
+
+Based on `drizzle.config.ts`, the project plans to add:
+- `src/infrastructure/database/schema.ts` - Drizzle schema definitions
+- `drizzle/` - Migration files
+
+---
+
+## 10. Structure Templates
+
+### New Feature Template
+
+```typescript
+// src/features/{feature}/index.ts
+import { Router } from 'ultimate-express';
+import { validateRequest } from '../../lib/validateRequest.js';
+import { getItems, createItem } from './controller.js';
+import { CreateItemSchema } from './schemas.js';
+
+export const {feature}Router = Router();
+
+{feature}Router.get('/', getItems);
+{feature}Router.post('/', validateRequest({ body: CreateItemSchema }), createItem);
+```
+
+```typescript
+// src/features/{feature}/controller.ts
+import type { RequestHandler } from 'ultimate-express';
+
+export const getItems: RequestHandler = (_req, res) => {
+    res.json([]);
+};
+
+export const createItem: RequestHandler = (req, res) => {
+    res.status(201).json(req.body);
+};
+```
+
+```typescript
+// src/features/{feature}/schemas.ts
+import { z } from 'zod';
+import { registry } from '../../lib/openapi.js';
+
+export const ItemSchema = z.object({
+    id: z.number().int().positive(),
+    name: z.string().min(1),
+}).openapi('Item');
+
+export const CreateItemSchema = z.object({
+    name: z.string().min(1),
+}).openapi('CreateItem');
+
+registry.registerPath({
+    method: 'get',
+    path: '/api/{feature}',
+    tags: ['{Feature}'],
+    responses: {
+        200: {
+            description: 'List all items',
+            content: { 'application/json': { schema: z.array(ItemSchema) } },
+        },
+    },
+});
+```
+
+```typescript
+// src/features/{feature}/{feature}.test.ts
+import { describe, expect, it, vi } from 'vitest';
+import type { Request, Response } from 'ultimate-express';
+import { getItems } from './controller.js';
+
+describe('GET /api/{feature}', () => {
+    it('returns empty array', () => {
+        const json = vi.fn();
+        const res = { json } as unknown as Response;
+        const req = {} as Request;
+
+        getItems(req, res, vi.fn());
+
+        expect(json).toHaveBeenCalledWith([]);
+    });
+});
+```
+
+---
+
+## 11. Structure Enforcement
+
+### Validation Tools
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| TypeScript | Type safety | `pnpm typecheck` |
+| Biome | Linting & formatting | `pnpm biome check .` |
+| Knip | Unused code detection | `pnpm knip` |
+| Vitest | Test execution | `pnpm test` |
+
+### Code Quality Rules (Biome)
+
+- **Indent**: Tabs
+- **Line width**: 100 characters
+- **Quotes**: Single quotes
+- **Semicolons**: Required
+- **Trailing commas**: ES5 style
+- **Imports**: Auto-organized
+
+### Recommended Pre-commit Checks
+
+```bash
+pnpm typecheck && pnpm biome check . && pnpm test
+```
+
+---
+
+## Maintaining This Blueprint
+
+This document should be updated when:
+- New feature modules are added
+- Project structure patterns change
+- Build or test configuration changes
+- New shared libraries are introduced
+
+**Document Version:** 1.0  
+**Last Updated:** November 25, 2025  
+**Generated By:** GitHub Copilot - Folder Structure Blueprint Generator

package/templates/backend/README.md

@@ -0,0 +1,99 @@
+
+# Cybermate API
+
+Fast TypeScript backend starter kit with Ultimate Express, Scalar API docs, and Drizzle ORM.
+
+## Features & Stack
+- Ultimate Express (Express framework)
+- TypeScript
+- Drizzle ORM (PostgreSQL)
+- Scalar API Docs
+- Biome (lint/format)
+- Vitest (testing)
+- pnpm (package manager)
+
+## Quick Start
+```bash
+pnpm install
+cp .env.example .env # edit as needed
+pnpm dev # start dev server
+```
+
+## Project Structure
+```
+cybermate-api/
+├── src/
+│   ├── index.ts              # App entry
+│   └── features/
+│       ├── health/           # Health check
+│       └── orders/           # Orders feature
+├── build/                    # Compiled output
+├── biome.json                # Biome config
+├── drizzle.config.ts         # Drizzle ORM config
+├── tsconfig.json             # TypeScript config
+└── package.json
+```
+
+### Feature Module Structure
+```
+features/{feature}/
+├── index.ts        # Router
+├── controller.ts   # HTTP handlers
+├── service.ts      # Business logic (optional)
+├── repository.ts   # DB access (optional)
+├── schema.ts       # Validation (optional)
+├── types.ts        # Types (optional)
+└── *.test.ts       # Unit tests
+```
+
+## Naming Conventions
+| Type                | Convention             | Example                |
+|---------------------|-----------------------|------------------------|
+| Folders             | lowercase-hyphenated  | `user-management/`     |
+| Files               | lowercase-hyphenated  | `controller.ts`        |
+| Test files          | `*.test.ts`           | `orders.test.ts`       |
+| Types/Interfaces    | PascalCase            | `Order`, `ApiResponse` |
+| Variables/Functions | camelCase             | `getOrders`            |
+| Constants           | UPPER_SNAKE_CASE      | `API_URL`              |
+| Routers             | camelCase+Router      | `ordersRouter`         |
+
+## API Endpoints
+- `GET /api/health` - Health check
+- `GET /api/orders` - List orders
+- `POST /api/orders` - Create order
+- `GET /api/docs` - API docs (Scalar)
+
+## Add a Feature
+1. Create `src/features/{feature}/`
+2. Add `controller.ts`, `index.ts`, etc.
+3. Mount router in `src/index.ts`
+
+## Testing
+- Use Vitest, place tests as `*.test.ts` next to code
+
+## Code Style
+- Format/lint: `pnpm biome check .`
+- Indent: tabs, line width: 100, single quotes, semicolons
+
+## Env Example
+```env
+PORT=3000
+DATABASE_URL=postgres://user:pass@localhost:5432/db
+```
+
+## Best Practices
+- Use named exports
+- Use `.js` for local imports
+- Type all handlers: `(req: Request, res: Response)`
+- Use Zod for validation
+- Keep features modular
+
+## License
+[Your License Here]
+
+## Links
+- [Ultimate Express](https://github.com/sinclairzx81/ultimate-express)
+- [Drizzle ORM](https://orm.drizzle.team/)
+- [Scalar](https://scalar.com/)
+- [Biome](https://biomejs.dev/)
+- [Vitest](https://vitest.dev/)

package/templates/backend/biome.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.0.6/schema.json",
+  "vcs": {
+    "enabled": false,
+    "clientKind": "git",
+    "useIgnoreFile": false
+  },
+  "files": {
+    "ignoreUnknown": false
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "tab",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noExplicitAny": "warn"
+      },
+      "style": {
+        "useConst": "error",
+        "useTemplate": "warn"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingCommas": "es5",
+      "semicolons": "always"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

package/{template → templates/backend}/drizzle.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'drizzle-kit';
 
 export default defineConfig({
-  schema: './src/infrastructure/database/schema.ts',
+  schema: './src/infrastructure/database/schema.ts', // TODO: update when fix database repo
   out: './drizzle',
   dialect: 'postgresql',
   dbCredentials: {