micheleangioni/create-nextjs-ddd-auth-db

Objective

Create a brand new Next.js app that satisfies all requested architecture and feature requirements. It includes App Router API endpoints, frontend pages, DDD structure, database integration, Google authentication with better-auth, tests, and linter. Keep the skill itself code-free: generate application code only inside the user-selected target folder.

Required Workflow

Follow this sequence exactly.

1) Ask Initial Questions First

Ask the user:

1. App name
2. Folder where the new app should be created
3. Database to use
4. Library to manage that database. When the user is unsure about the library, propose:

• MongoDB: mongoose
• DynamoDB: dynamoose
• SQL dialects: prisma

5. Whether Jest or Vitest should be used as testing library
6. Whether ESLint or Oxlint should be used as linting library

Confirm the final choices before continuing.

2) Present Plan Before Implementation

Create a concrete implementation plan and present it to the user before changing files. Wait for explicit approval.

The plan must include:

• Discovery confirmation
• Version research and documentation review
• Scaffolding
• instrumentation.ts file setup to:
  • Log the node version, next.js version and NODE_ENV variable at startup
  • To validate the environment variables and log any critical missing ones at startup
  • To initializate the database connection and log success or failure
  • To log the server startup completion
• Tactical DDD folder setup
• Feature implementation
• Tests
• Linting setup, and Typescript configured in strict mode
• Documentation updates
• Final validation

3) Research Latest Versions and Official Docs

Before any installation, verify latest stable versions and usage from official sources:

• Next.js docs: https://nextjs.org/docs
• Next.js installation guide: https://nextjs.org/docs/app/getting-started/installation
• better-auth docs
• Chosen database library docs
• Chosen testing library docs (Jest or Vitest)
• Chosen linter library docs (ESLint or Oxlint)

Use the latest stable versions available at execution time. Do not assume versions from memory.

4) Scaffold the App with Latest Next.js Features

Create the app in the chosen folder with the chosen name and latest Next.js setup. Use current recommended options from Next.js docs, including App Router and src/ structure.

Install and configure:

• better-auth (Google Auth)
• Selected testing library
• Selected linter library
• Selected database library and required driver packages

5) Implement Required Tactical DDD Structure

Create the following structure:

• <app_name>/src/__tests__
• <app_name>/src/app
• <app_name>/src/app/api
• <app_name>/src/application
• <app_name>/src/domain
• <app_name>/src/infrastructure
• <app_name>/src/shared
• <app_name>/src/shared/logger
• <app_name>/docs

6) Implement Required Features

Implement all of the following:

• Database connection under src/infrastructure, aligned with the selected database and library
• A simple logging utility under src/shared/logger that can be used across the app
• The Abstract Entity Class BaseEntity with the following methods:
  • addDomainEvent(domainEvent: DomainEventInterface)
  • releaseDomainEvents(): DomainEventInterface[]

where DomainEventInterface is:

interface DomainEventInterface {
  getEventAggregate(): string;
  getEventName(): string;
  getEventData(): Record<string, unknown>;
}

• Example User entity in domain layer extending BaseEntity
• At least one concrete sample domain event implementation for the sample domain (for example, a User-related event) so the event catalog is not empty
• User repository abstraction + implementation
• Application service for user retrieval
• GET /users endpoint in App Router under src/app/api, with limit and offset query parameters, returning paginated users
• Homepage page with a Google Auth button powered by better-auth
• Tests for domain/application/infrastructure/API behavior under src/__tests__

7) Environment and Documentation

Create:

• .env.example with every required variable (app URL, auth values, Google OAuth credentials, DB settings, and anything else needed)
• docs/endpoints.yaml listing available endpoints with method, path, purpose, and auth requirements in OpenAPI format
• docs/asyncapi.yaml as the event catalog source of truth, using a valid AsyncAPI document that describes emitted domain events only
• The AsyncAPI document must be transport-agnostic by default unless the user explicitly asks for messaging infrastructure details
• The AsyncAPI document must include:
  • Document metadata including asyncapi and info with basic title and version
  • One logical channel per emitted domain event
  • One message per event with payload schema
  • Reusable schemas under components when payload structures are shared
• Event payload schemas must document the domain event aggregate, event name, and event data structure

Update the app's README.md with setup, environment, run, test, lint, endpoint usage instructions, and where docs/asyncapi.yaml lives and how it should be used as the event catalog.

8) Validate and Iterate Until Complete

Run lint and tests. Fix failures and re-run until passing.

Verify:

• App starts correctly
• Homepage renders and auth button is present
• /users endpoint works
• Required structure and docs exist
• docs/asyncapi.yaml exists and documents the emitted events implemented in code

If any requirement is unmet, iterate until complete.

Non-Negotiable Constraints

• Keep all packages on latest stable versions at run time.
• Do not stop after scaffolding; continue until all requirements are satisfied and validated.