English · Portuguese

About   |    AI-First Development   |    Technologies   |    Installation   |    License

🔖 About

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 v6 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. By providing a well-defined architecture with features like authentication, role-based access control (RBAC), and file management out of the box, it allows developers (both human and AI) to focus on building unique business logic instead of boilerplate code.

🏗️ Architecture Overview

graph TD
    subgraph "Frontend (Inertia.js)"
        FE_UI[React Components & Pages]
        FE_HOOKS["Hooks (useAuth, useApi)"]
        FE_UTILS[Utilities & Types]
    end

    subgraph "Backend (AdonisJS)"
        BE_ROUTES[Routes]
        BE_MW["Middleware (Auth, ACL)"]
        BE_CTRL[Controllers]
        BE_SERVICES[Services]
        BE_REPOS[Repositories]
        BE_MODELS[Lucid Models]
    end

    subgraph "Shared"
        SHARED_TYPES[TypeScript Types]
        SHARED_CONFIG[Config Files]
    end

    subgraph "Data Layer"
        DB[(PostgreSQL)]
        CACHE[(Redis)]
    end

    FE_UI --> BE_ROUTES
    BE_ROUTES --> BE_MW
    BE_MW --> BE_CTRL
    BE_CTRL --> BE_SERVICES
    BE_SERVICES --> BE_REPOS
    BE_REPOS --> BE_MODELS
    BE_MODELS --> DB

    BE_SERVICES --> CACHE
    FE_HOOKS --> BE_ROUTES

    FE_UTILS --> SHARED_TYPES
    BE_CTRL --> SHARED_TYPES

Loading

🚀 AI-First Development

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 and Opinionated Architecture: The clear separation of concerns (controllers, services, repositories) makes it easy for an AI to locate, understand, and modify specific parts of the codebase with precision.
• 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.

🌟 Key Features

• 🔐 Multi-Guard Authentication: Ready-to-use JWT-based authentication.
• 👥 Advanced Role-Based Access Control (RBAC): Manage user permissions with roles and fine-grained rules.
• 📁 File Management: Pre-configured file upload service with support for local and S3 drivers.
• ⚡️ Full-Stack Reactivity: The power of React combined with the simplicity of a traditional server-rendered app, thanks to Inertia.js.
• 🎨 UI Components: A set of beautiful, reusable UI components built with shadcn/ui, Tailwind CSS, and lucide-react.
• ✅ Type-Safe API: Auto-completion and type checking for API calls and props.
• 🏥 Health Checks: Integrated health check endpoint for monitoring.

💻 Technologies

• AdonisJS v6: A robust Node.js framework for the backend.
• React 19: A powerful library for building user interfaces.
• Inertia.js: 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.
• Redis: Used for caching and session management.
• Vite: For a lightning-fast frontend development experience.
• Tailwind CSS: A utility-first CSS framework for rapid UI development.

📦 Installation

✔️ Prerequisites

• Node.js (v18 or higher)
• pnpm (or npm/yarn)
• Docker (for running PostgreSQL and Redis)

🚀 Getting Started

1. Clone the repository:

   git clone https://github.com/gabrielmaialva33/adonis-web-kit.git
   cd adonis-web-kit

2. Install dependencies:

   pnpm install

3. Setup environment variables:

   cp .env.example .env

   Open the .env file and configure your database credentials and other settings.

4. Run database migrations:

   node ace migration:run

5. Start the development server:

   pnpm dev

   Your application will be available at http://localhost:3333.

📜 Available Scripts

• pnpm dev: Starts the development server with HMR.
• pnpm build: Compiles the application for production.
• pnpm start: Runs the production-ready server.
• pnpm test: Executes unit tests.
• pnpm test:e2e: Executes end-to-end tests.
• pnpm lint: Lints the codebase.
• pnpm format: Formats the code with Prettier.

📝 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Made with ❤️ by the community.