About | AI-First Development | Technologies | Installation | Docker | License
Adonis Web Kit is a modern, opinionated, and AI-first full-stack starter kit designed to accelerate the development of robust web applications. It combines a powerful AdonisJS v7 backend with a dynamic React 19 and Inertia.js frontend, all within a unified monorepo structure.
This project is not just a collection of technologies; it's a foundation engineered for efficiency, scalability, and seamless collaboration with AI development partners. The backend is organized into domain modules and ships with multi-guard authentication, role-based access control (RBAC), N:N multi-tenancy, and file management out of the box — letting developers (both human and AI) focus on unique business logic instead of boilerplate.
The backend is modular (domain-driven): each domain (auth, users, roles, permissions, files, audits,
tenants, health, web) owns its controllers, services, repositories, models, validators, and routes under
app/modules/<domain>/. Cross-cutting code (middleware, JWT guard, shared repository and services) lives in app/shared/, and
typed exceptions in app/exceptions/.
graph TD
subgraph "Frontend (Inertia.js)"
FE_UI[React 19 Pages]
FE_LAYOUT["Admin Shell (sidebar + tenant switcher)"]
FE_COMPONENTS["UI Components (Metronic / shadcn-style)"]
end
subgraph "Backend — app/modules/* (AdonisJS v7)"
BE_ROUTES["Module routes.ts"]
BE_CTRL[Controllers]
BE_SERVICES[Services]
BE_REPOS[Repositories]
BE_MODELS[Lucid Models]
end
subgraph "app/shared"
SH_MW["Middleware (auth, acl, permission, ownership, tenant)"]
SH_JWT[Custom JWT Guard]
end
subgraph "Data Layer"
DB[(PostgreSQL)]
CACHE[(Redis — cache, sessions, queue)]
end
FE_UI --> BE_ROUTES
FE_LAYOUT --> FE_COMPONENTS
BE_ROUTES --> SH_MW
SH_MW --> SH_JWT
SH_MW --> BE_CTRL
BE_CTRL --> BE_SERVICES
BE_SERVICES --> BE_REPOS
BE_REPOS --> BE_MODELS
BE_MODELS --> DB
BE_SERVICES --> CACHE
This starter kit is uniquely designed to maximize the effectiveness of AI-assisted coding.
- Unified Context (Monorepo): Having backend and frontend code in a single repository provides a complete context for AI tools, enabling them to generate more accurate and cohesive code that spans the full stack.
- Strongly-Typed Foundation: End-to-end TypeScript usage creates a clear contract between the frontend, backend, and API layers. This reduces ambiguity and allows AI to understand data structures and function signatures, leading to fewer errors.
- Modular, Domain-Driven Architecture: Each domain is self-contained under
app/modules/<domain>/, so an AI (or a human) can locate, understand, and modify a feature end to end without spelunking across unrelated layers. - Focus on Business Logic: With boilerplate for authentication, permissions, and file storage already handled, AI can be directed to solve higher-level business problems from day one.
- 🔐 Complete Account Lifecycle: Short-lived access JWTs, rotating opaque refresh tokens, email verification, privacy-preserving password reset, web cookies, API access tokens, and authenticated self-deletion.
- 👥 Advanced Global RBAC: Roles, permissions, direct user permissions, role inheritance, contextual ownership checks, cached authorization, and permission-aware Inertia navigation. Tenant membership roles remain workspace metadata.
- 🏢 Multi-Tenancy (N:N): Users belong to many workspaces through
user_tenants. Public registration can create a personal workspace, authenticated users can create more, and the verified JWT carries the active tenant. - 📁 File Management: Tenant-scoped upload, pagination, opening, and owner-aware deletion with local, S3, Spaces, R2, and GCS drivers.
- ⚡️ Full-Stack Reactivity: The power of React combined with the simplicity of a traditional server-rendered app, thanks to Inertia.js.
- 🎨 UI Component Library: ~78 Metronic (shadcn-style) components built on Radix UI, Tailwind CSS v4, and
lucide-react, plus an admin shell with sidebar, tenant switcher, and theme toggle. - ✅ Type-Safe Stack: End-to-end TypeScript with type checking across backend and frontend.
- 🏥 Health Checks: Integrated health check endpoint for monitoring.
- AdonisJS v7: A robust Node.js framework for the backend (runs TypeScript directly via
@poppinss/ts-exec). - Node.js 24 LTS: The runtime (
.nvmrc→v24.13.0). - React 19: A powerful library for building user interfaces.
- Inertia.js v3: The glue that connects the modern frontend with the backend.
- TypeScript: For type safety across the entire stack.
- PostgreSQL: A reliable and powerful relational database (SQLite available for tests).
- Redis: Used for caching, sessions, and the Bull queue.
- Vite: For a lightning-fast frontend development experience.
- Tailwind CSS v4: A utility-first CSS framework powering the Metronic component library.
- TanStack Table v9: Headless data grids (the
DataGridcomponents underinertia/components/ui/). - TanStack Query: Server-state caching for client-side fetches.
- React Hook Form + Zod: Form state and schema validation.
- Radix UI + lucide-react: Primitives and icons behind the component library.
- Recharts, dnd-kit, Motion: Charts, drag-and-drop, and animation.
- Lucid ORM: Models, migrations, and query building with a snake_case naming strategy.
- VineJS: Request validation at the edge.
- Bull Queue: Background jobs on top of Redis.
- Japa: Backend unit, functional, and browser suites (browser via Playwright).
- Vitest + Testing Library + MSW: Frontend tests.
Note on TypeScript. The
typescriptdependency is aliased to@typescript/typescript6while TS 7 ships astypescript-native.typescript-eslintdoes not support the TS 7 API yet (#10940) and resolves TypeScript through a peer dependency, so the two run side by side: ESLint gets the TS 6 API, whilepnpm typecheckandpnpm builduse the TS 7tsc. Collapse them back into a singletypescriptentry once typescript-eslint catches up.
- Node.js 24 LTS (
.nvmrc→v24.13.0) - pnpm 11 (
packageManagerpins the tested release) - PostgreSQL and Redis — both are required for development and tests
- Docker Compose is recommended for PostgreSQL, Redis, and the bundled Mailpit inbox
-
Clone the repository:
git clone https://github.com/gabrielmaialva33/adonis-web-kit.git cd adonis-web-kit -
Install dependencies:
pnpm install
-
Create the environment file and application key:
cp .env.example .env pnpm ace generate:key
Review
APP_NAME,APP_URL, database credentials, security secrets, mail settings, andREGISTRATION_WORKSPACE_MODEbefore continuing. -
Start PostgreSQL, Redis, and Mailpit:
docker compose up -d postgres redis mailpit
Mailpit receives development emails on SMTP port
1025; openhttp://localhost:8025to inspect the inbox. Skip services you already run locally and update.envaccordingly. -
Run database migrations and development seeders:
pnpm ace migration:run pnpm ace db:seed
Until the first stable release, migrations describe a clean installation. Unshipped schema changes are folded into their original
create_*migration; recreate disposable dev/test databases instead of stacking compatibility alters. -
Start the development server:
pnpm dev
Your application will be available at
http://localhost:3333.
The starter keeps reusable product identity and onboarding decisions in environment variables:
| Variable | Purpose |
|---|---|
APP_NAME, APP_URL, APP_SOURCE_URL |
Branding, generated links, and optional source links |
ACCESS_TOKEN_SECRET, REFRESH_TOKEN_SECRET |
Independent API token secrets |
EMAIL_VERIFICATION_SECRET, PASSWORD_RESET_SECRET |
HMAC secrets for single-use account links |
JWT_ISSUER, JWT_AUDIENCE, JWT_COOKIE_NAME |
JWT identity and web cookie configuration |
REGISTRATION_WORKSPACE_MODE |
personal creates an owned workspace on sign-up; none leaves onboarding to the product |
DEMO_PAGES_ENABLED |
Enables the component and data-grid reference pages |
DRIVE_DISK |
Selects fs, s3, spaces, r2, or gcs storage |
Do not reuse the development fallbacks in production. Generate long independent secrets and keep them outside version control.
| Script | What it does |
|---|---|
pnpm dev |
Starts the development server with HMR. |
pnpm build |
Compiles the application for production. |
pnpm start |
Runs the production-ready server (node bin/server.js). |
pnpm ace <cmd> |
Runs any AdonisJS ace command (e.g. pnpm ace migration:run). |
pnpm test |
Executes backend unit tests (Japa). |
pnpm test:e2e |
Executes all backend suites (unit + functional + browser). |
pnpm test:ui |
Executes frontend tests (Vitest). |
pnpm test:ui:watch |
Frontend tests in watch mode. |
pnpm typecheck |
Type-checks both backend and frontend. |
pnpm lint |
Lints the codebase. |
pnpm lint:fix |
Lints and auto-fixes the backend sources. |
pnpm format |
Formats the code with Prettier. |
pnpm docker |
Migrates, seeds, then boots the server for a local container flow. |
Note: there is no
node aceanymore — AdonisJS v7 runs TypeScript directly, so every ace command goes throughpnpm ace <cmd>.
A Dockerfile (multi-stage, with a production target) and a docker-compose.yml ship with the
project.
Local infrastructure — the common setup, with the app running on the host via pnpm dev:
docker compose up -d postgres redis mailpitFull stack — app, PostgreSQL, Redis, and Mailpit containerized:
docker compose up --buildThe app container waits for its dependencies, runs pending migrations, and starts the server on
http://localhost:3333. Mailpit is available on http://localhost:8025. Compose ships placeholder
secrets; generate a real APP_KEY and provide independent production secrets before using the full stack outside a scratch environment:
export APP_KEY=$(pnpm ace generate:key --show | cut -d' ' -f3)--show prints APP_KEY = <key> instead of writing it into .env, hence the cut.
Port 3333 must be free — if you already have
pnpm devrunning on the hos 633D t, the app container will fail to bind.
Every push to master/develop and every PR against master runs the
CI workflow: lint, type check (backend + frontend), the full backend
suite (unit + functional + browser on Playwright Chromium), the frontend tests, and a production
build — against real PostgreSQL and Redis service containers.
This project is licensed under the MIT License. See the LICENSE file for details.
Made with ❤️ by the community.