adonisjs-architecture-skill

Opinionated architecture decisions, patterns, and project structure for AdonisJS v6 API kit applications. Use when the user asks about architecture decisions, project structure, pattern selection, separation of concerns, service layers, repository patterns, domain-driven design, or mentions how to organize, which pattern to use, best practices, or architecture. Also trigger when the user is creating controllers, services, repositories, actions, DTOs, validators, events, listeners, state machines, or any domain logic classes in an AdonisJS v6 project. Also trigger for observability, telemetry, tracing, metrics, OpenTelemetry, OTEL, Prometheus, prom-client, distributed tracing, spans, instrumentation, monitoring, or setting up a /metrics endpoint. Even if the user doesn't explicitly say "architecture," use this skill whenever structural or organizational decisions are being made in an AdonisJS v6 codebase.

Foundational architecture for Nuxt 4 + Vue 3 + shadcn-nuxt applications. Use when starting new projects, understanding project structure, or making architectural decisions about directory organization, technology choices, and pattern selection.

Authentication with Keycloak and permission-based authorization. Use when implementing login/logout, protecting pages with permissions, checking permissions in components, or understanding the auth flow.

Vue component patterns with Composition API and script setup. Use when creating components, understanding script setup order convention, organizing component directories, or implementing component patterns like slideovers, modals, and tables.

Creating custom Vue composables with proper patterns. Use when building reusable stateful logic, shared state management, or encapsulating feature-specific behavior.

Nuxt and app configuration files. Use when configuring nuxt.config.ts, app.config.ts, environment variables, runtime config, or understanding how configuration flows through the application.

Error handling with error classes, handlers, and interceptors. Use when handling API errors, displaying validation errors, configuring error handlers, or implementing error interceptors.

Feature module pattern organizing domain logic into queries, mutations, and actions. Use when implementing data fetching with filters, API mutations with loading states, business logic with UI feedback, or organizing domain-specific code.

Form handling with useFormBuilder and native forms. Use when creating forms, handling validation errors, managing form state, or building form-based slideovers and modals.

Working with Nuxt layers (base, shadcn-nuxt, x-ui) that provide shared functionality. Use when understanding layer architecture, importing from layers, extending layer functionality, or creating new layers.

File-based routing with page patterns for lists, details, and navigation. Use when creating pages, defining page meta (permissions, layouts), implementing list/detail patterns, or setting up breadcrumbs and headers.

Real-time features with Laravel Echo and WebSockets. Use when subscribing to channels, listening for events, implementing live updates, or managing channel subscriptions.

Table components with column builder pattern and DataTable. Use when creating data tables, defining columns with custom cells, implementing row actions, or building reusable table configurations.

Optional single-purpose action classes for AdonisJS v6. Use when a service method grows complex (beyond ~50 lines), needs to be reused across multiple callers, or when the user mentions actions, domain operations, composing workflows, or extracting logic out of services. Actions are optional — start with services, extract to actions when complexity demands it.

Thin HTTP layer controllers for AdonisJS v6. Controllers contain zero domain logic, only HTTP concerns. Use when working with controllers, HTTP layer, API vs web patterns, or when user mentions controllers, routes, HttpContext, or HTTP responses in an AdonisJS project.

Data Transfer Objects for AdonisJS v6. Plain TypeScript interfaces and classes used to move validated data between the HTTP layer, actions, and services. Use when handling request payloads, structured data transfer, or when the user mentions DTOs, data objects, payload types, or typed interfaces for domain operations.

TypeScript string enums with labels and business logic for AdonisJS v6. Use when working with enums, status values, fixed sets of options, or when the user mentions enums, status enums, enum cases, or finite value sets. Also use when typing Lucid model columns or validating enum fields with VineJS.

Event-driven architecture with AdonisJS Emitter. Use when working with events, listeners, emitter, event classes, decoupling side effects, or when user mentions events, emit, listen, emitter, event listeners, AdonisJS events.

Custom exceptions with static factories and self-contained HTTP responses. Use when working with error handling, custom exceptions, business rule violations, or when user mentions exceptions, custom exception, error handling, HTTP exceptions, exception handler, AdonisJS exceptions.

Background jobs and queue processing for async tasks. Use when working with queued jobs, background processing, job retries, scheduled jobs, or when user mentions jobs, queues, workers, async processing, background tasks, AdonisJS queue.

Lucid ORM model patterns and database layer. Use when working with models, database entities, Lucid ORM, or when user mentions models, lucid, relationships, column types, hooks, database entities, AdonisJS models.

Multi-tenant application architecture patterns for AdonisJS. Use when working with multi-tenant systems, tenant isolation, tenant scoping, database-per-tenant, schema-per-tenant, or single-database tenancy in AdonisJS. Trigger whenever the user mentions multi-tenancy, tenants, tenant middleware, tenant context, SaaS architecture, tenant databases, tenant migrations, or tenant-aware models in an AdonisJS project — even if they don't explicitly say "multi-tenant."

Package development and extraction of reusable code for AdonisJS using the official pkg-starter-kit. Use when working with package development, creating npm packages, extracting reusable code, writing service providers, configure hooks, stubs, codemods, or when user mentions packages, npm packages, extract package, reusable code, package development, publish package, service provider for a package, starter kit, or asks how to create an AdonisJS addon/plugin.

Authorization policies for resource access control in AdonisJS using Bouncer. Use when working with authorization, permissions, access control, policies, abilities, or when user mentions policies, authorization, permissions, can, ability checks, bouncer, role-based access, ownership checks, who can do what, or asks how to restrict actions to specific users or roles in an AdonisJS project.

Code quality tooling for AdonisJS — ESLint, Prettier, TypeScript strict mode, test coverage, and CI/CD. Use when working with code quality, static analysis, formatting, linting, or when user mentions ESLint, Prettier, TypeScript strict, tsc, code style, linting, code quality, CI/CD, pre-commit hooks, test coverage, architecture tests, naming conventions, or asks how to enforce coding standards in an AdonisJS project.

Composable query builder patterns for AdonisJS Lucid. Use when working with database queries, query scopes, reusable query logic, filtering, sorting, pagination, complex where clauses, or when user mentions query builders, query scopes, model scopes, composable queries, query objects, database queries, complex queries, eager loading, preloading, subqueries, raw queries, or asks how to organize Lucid query logic in an AdonisJS project.

Routing, middleware, and permission patterns for AdonisJS. Use when working with routes, route groups, resource routes, named routes, middleware, route-level authorization, permission guards, role-based access, or when user mentions routing, middleware, named middleware, route protection, auth guards, RBAC, abilities, bouncer, route organization, API versioning, or any route/middleware configuration in an AdonisJS project.

Service layer for external API integration using the manager/driver pattern in AdonisJS. Use when working with external APIs, third-party services, payment gateways, email providers, SMS, file storage, or when user mentions services, service layer, external API, manager pattern, driver pattern, driver swapping, null driver, API integration, or wrapping third-party SDKs in an AdonisJS project. Also trigger when user asks how to abstract external dependencies for testability or swap implementations at runtime.

State machine patterns for AdonisJS Lucid models. Use when working with complex state management, state transitions, workflow status, order status, or when user mentions state machines, state transitions, transition validation, transition guards, side effects on state change, finite state machines, FSM, status workflows, or needs to model domain objects with well-defined lifecycle states. Also trigger when user asks how to handle status columns that have rules about which transitions are allowed.

Comprehensive testing patterns with Japa for AdonisJS. Use when working with tests, testing patterns, or when user mentions testing, tests, Japa, assertions, mocking, factories, unit tests, functional tests, API tests, browser tests, test suites, expect, assert, database testing, HTTP testing in an AdonisJS project. Also trigger when user asks how to test controllers, services, actions, models, validators, middleware, or any AdonisJS feature.

VineJS validation patterns for AdonisJS. Use when working with form validation, request validation, custom validation rules, custom error messages, error reporters, conditional validation, data transformation, reusable schemas, schema composition, custom schema types, or any VineJS usage in an AdonisJS project. Also trigger when user mentions validators, vine, validation messages, field context, validation helpers, or extending VineJS.

Immutable value objects for domain values in AdonisJS (TypeScript). Use when working with domain values, immutable objects, or when user mentions value objects, immutable values, domain values, money objects, coordinate objects, email address objects, or any typed domain concept in an AdonisJS project. Also trigger when user wants to encapsulate validation, equality, or arithmetic for a domain primitive.