English · Portuguese

About   |    Technologies   |    Tools   |    Installation   |    License

🔖 About

Base ACL is a modular access control list API built with AdonisJS v6 that provides a robust foundation for authentication and role-based access control. The API follows clean architecture principles with clear separation of concerns and is designed to serve as a base for multiple projects.

🏗️ Architecture Overview

graph TB
    subgraph "Client Layer"
        WEB[Web Apps]
        MOB[Mobile Apps]
        API[External APIs]
    end

    subgraph "API Gateway - v1"
        ROUTES["/api/v1/*"]
        MW[Middleware Stack]
    end

    subgraph "Modules"
        AUTH[Auth Module<br/>JWT, Sessions]
        USER[User Module<br/>CRUD, Profile]
        ROLE[Role Module<br/>RBAC, Hierarchy]
        PERM[Permission Module<br/>Context-aware, Inheritance]
        FILE[File Module<br/>Upload, Storage]
        AUDIT[Audit Module<br/>Logging, Analytics]
        HEALTH[Health Module<br/>Status, Monitoring]
    end

    subgraph "Core Services"
        JWT[JWT Service]
        HASH[Hash Service]
        VALIDATOR[Validator Service]
        STORAGE[Storage Service]
    end

    subgraph "Data Layer"
        TS[(PostgreSQL<br/>Main Database)]
        REDIS[(Redis<br/>Cache & Sessions)]
        PGREST[PostgREST<br/>Auto-generated REST API]
    end

    WEB --> ROUTES
    MOB --> ROUTES
    API --> ROUTES

    ROUTES --> MW
    MW --> AUTH
    MW --> USER
    MW --> ROLE
    MW --> PERM
    MW --> FILE
    MW --> AUDIT
    MW --> HEALTH

    AUTH --> JWT
    AUTH --> HASH
    USER --> VALIDATOR
    FILE --> STORAGE
    PERM --> REDIS
    AUDIT --> TS

    USER --> TS
    ROLE --> TS
    PERM --> TS
    AUTH --> TS
    AUTH --> REDIS
    AUDIT --> TS

    TS --> PGREST

    style ROUTES fill:#4A90E2
    style TS fill:#336791
    style REDIS fill:#DC382D
    style PGREST fill:#008080

Loading

🔐 Authentication Flow

sequenceDiagram
    participant C as Client
    participant API as API Gateway
    participant AUTH as Auth Module
    participant JWT as JWT Service
    participant DB as PostgreSQL
    participant REDIS as Redis Cache

    C->>API: POST /api/v1/sessions/sign-in
    API->>AUTH: Validate credentials
    AUTH->>DB: Find user by email
    DB-->>AUTH: User data
    AUTH->>AUTH: Verify password hash
    AUTH->>JWT: Generate tokens
    JWT-->>AUTH: Access & Refresh tokens
    AUTH->>REDIS: Store session
    AUTH-->>C: Return tokens + user data

    Note over C,API: Subsequent requests

    C->>API: GET /api/v1/users (Bearer token)
    API->>AUTH: Validate JWT
    AUTH->>REDIS: Check session
    REDIS-->>AUTH: Session valid
    AUTH-->>API: User authenticated
    API-->>C: Return protected resource

Loading

📁 Module Structure

graph TD
    subgraph "Application Structure"
        APP[app/]
        MODULES[modules/]

        subgraph "User Module"
            USER_M[user/]
        end
        subgraph "Role Module"
            ROLE_M[role/]
        end
        subgraph "Permission Module"
            PERM_M[permission/]
        end
        subgraph "File Module"
            FILE_M[file/]
        end
        subgraph "Audit Module"
            AUDIT_M[audit/]
        end
        subgraph "Health Module"
            HEALTH_M[health/]
        end
        subgraph "Ownership Module"
            OWNER_M[ownership/]
        end
    end

    APP --> MODULES
    MODULES --> USER_M
    MODULES --> ROLE_M
    MODULES --> PERM_M
    MODULES --> FILE_M
    MODULES --> AUDIT_M
    MODULES --> HEALTH_M
    MODULES --> OWNER_M

Loading

🌟 Key Features

Core Features

• 🔐 JWT Authentication: Secure token-based authentication with refresh tokens
• 👥 Role-Based Access Control: Fine-grained permissions with ROOT, ADMIN, USER, EDITOR, and GUEST roles
• 📁 Modular Architecture: Clean separation of concerns with feature modules
• 🗄️ PostgreSQL: Robust and reliable database
• 🚀 RESTful API: Well-structured endpoints following REST principles
• 📤 File Uploads: Secure file handling with multiple storage drivers
• 🏥 Health Monitoring: Built-in health check endpoints
• 🔒 Security First: Password hashing, CORS, rate limiting ready
• 📝 Request Validation: DTOs with runtime validation
• 🌐 i18n Ready: Internationalization support built-in
• 🔗 PostgREST Integration: Auto-generated REST API for direct database access

Advanced ACL Features

• 🎯 Context-Aware Permissions: Support for own, any, team, and department contexts
• 🔄 Permission Inheritance: Automatic permission inheritance through role hierarchy
• 📋 Comprehensive Audit Trail: Track all permission checks and access attempts
• ⚡ Redis-Cached Permissions: High-performance permission checking with intelligent caching
• 🏢 Resource Ownership: Built-in ownership system supporting team and department contexts
• 🔍 Granular Permission Control: Resource + Action + Context based permission system

Database Schema

erDiagram
    USERS ||--o{ USER_ROLES : has
    ROLES ||--o{ USER_ROLES : has
    USERS ||--o{ USER_PERMISSIONS : has
    USERS ||--o{ FILES : uploads
    ROLES ||--o{ ROLE_PERMISSIONS : has
    PERMISSIONS ||--o{ ROLE_PERMISSIONS : has
    PERMISSIONS ||--o{ USER_PERMISSIONS : has
    USERS ||--o{ AUDIT_LOGS : generates

    USERS {
        bigint id PK
        string first_name
        string last_name
        string email UK
        string username UK
        string password
        string avatar_url
        boolean is_online
        timestamp deleted_at
        timestamp created_at
        timestamp updated_at
    }

    ROLES {
        bigint id PK
        string name
        string slug UK
        string description
        timestamp created_at
        timestamp updated_at
    }

    PERMISSIONS {
        bigint id PK
        string name UK
        string resource
        string action
        string context
        string description
        timestamp created_at
        timestamp updated_at
    }

    USER_ROLES {
        bigint id PK
        bigint user_id FK
        bigint role_id FK
        timestamp created_at
        timestamp updated_at
    }

    ROLE_PERMISSIONS {
        bigint id PK
        bigint role_id FK
        bigint permission_id FK
        timestamp created_at
        timestamp updated_at
    }

    USER_PERMISSIONS {
        bigint id PK
        bigint user_id FK
        bigint permission_id FK
        boolean granted
        timestamp expires_at
        timestamp created_at
        timestamp updated_at
    }

    AUDIT_LOGS {
        bigint id PK
        bigint user_id FK
        string resource
        string action
        string context
        bigint resource_id
        string result
        string reason
        string ip_address
        string user_agent
        json metadata
        timestamp created_at
    }

    FILES {
        bigint id PK
        bigint owner_id FK
        string client_name
        string file_name
        bigint file_size
        string file_type
        string file_category
        string url
        timestamp created_at
        timestamp updated_at
    }

Loading

💻 Technologies

• Typescript
• Node.js
• AdonisJS
• PostgreSQL
• Redis - In-memory data store
• PostgREST - Auto-generated REST API
• Docker

🔧 Tools

• WebStorm
• Insomnia
• DataGrip

📦 Installation

✔️ Prerequisites

The following software must be installed:

• Node.js
• Git
• NPM or Yarn
• PostgreSQL or Docker

⬇️ Cloning the repository

  $ git clone https://github.com/gabrielmaialva33/base-acl-api.git

▶️ Running the application

• 📦 API

  $ cd base-acl-api
  # Dependencies install.
  $ yarn # or npm install
  # Config environment system
  $ cp .env.example .env
  # Data base creation.
  $ node ace migration:run # or docker-compose up --build
  # API start
  $ node ace serve --hmr # or pnpm dev

🔀 API Routes

The API is versioned and all endpoints are prefixed with /api/v1/. Below is the complete route structure:

🛣️ Route Organization

graph LR
    subgraph "Public Routes"
        HOME[GET /]
        HEALTH[GET /api/v1/health]
        SIGNIN[POST /api/v1/sessions/sign-in]
        SIGNUP[POST /api/v1/sessions/sign-up]
    end

    subgraph "Protected Routes"
        subgraph "User Routes"
            USER_LIST[GET /api/v1/users]
            USER_GET[GET /api/v1/users/:id]
            USER_CREATE[POST /api/v1/users]
            USER_UPDATE[PUT /api/v1/users/:id]
            USER_DELETE[DELETE /api/v1/users/:id]
        end

        subgraph "Admin Routes"
            ROLE_LIST[GET /api/v1/admin/roles]
            ROLE_ATTACH[PUT /api/v1/admin/roles/attach]
        end

        subgraph "File Routes"
            FILE_UPLOAD[POST /api/v1/files/upload]
        end
    end

    style HOME fill:#90EE90
    style HEALTH fill:#90EE90
    style SIGNIN fill:#90EE90
    style SIGNUP fill:#90EE90
    style ROLE_LIST fill:#FFB6C1
    style ROLE_ATTACH fill:#FFB6C1

Loading

📋 Route Details

Method	Endpoint	Description	Auth Required	Permission/Role
GET	/	API information	❌	-
GET	/api/v1/health	Health check	❌	-
POST	/api/v1/sessions/sign-in	User login	❌	-
POST	/api/v1/sessions/sign-up	User registration	❌	-
GET	/api/v1/verify-email	Verify user email	❌	-
POST	/api/v1/resend-verification-email	Resend verification email	✅	-
GET	/api/v1/me	Get current user profile	✅	-
GET	/api/v1/me/permissions	Get current user permissions	✅	-
GET	/api/v1/me/roles	Get current user roles	✅	-
GET	/api/v1/users	List users (paginated)	✅	users.list
GET	/api/v1/users/:id	Get user by ID	✅	users.read
POST	/api/v1/users	Create user	✅	users.create
PUT	/api/v1/users/:id	Update user	✅	users.update
DELETE	/api/v1/users/:id	Delete user	✅	users.delete
GET	/api/v1/admin/roles	List roles	✅	ROOT, ADMIN
PUT	/api/v1/admin/roles/attach	Attach role to user	✅	ROOT, ADMIN
GET	/api/v1/admin/permissions	List permissions	✅	permissions.list
POST	/api/v1/admin/permissions	Create permission	✅	permissions.create
PUT	/api/v1/admin/roles/permissions/sync	Sync role permissions	✅	permissions.update
PUT	/api/v1/admin/roles/permissions/attach	Attach permissions to role	✅	permissions.update
PUT	/api/v1/admin/roles/permissions/detach	Detach permissions from role	✅	permissions.update
PUT	/api/v1/admin/users/permissions/sync	Sync user permissions	✅	permissions.update
GET	/api/v1/admin/users/:id/permissions	Get user's direct permissions	✅	permissions.list
POST	/api/v1/admin/users/:id/permissions/check	Check user permissions	✅	permissions.list
POST	/api/v1/files/upload	Upload file	✅	files.create

🔄 Request/Response Flow

sequenceDiagram
    participant Client
    participant Router
    participant Middleware
    participant Controller
    participant Service
    participant Repository
    participant Database

    Client->>Router: HTTP Request
    Router->>Middleware: Route Match

    alt Protected Route
        Middleware->>Middleware: Auth Check
        Middleware->>Middleware: ACL Check
    end

    Middleware->>Controller: Request Validated
    Controller->>Service: Business Logic
    Service->>Repository: Data Access
    Repository->>Database: Query
    Database-->>Repository: Result
    Repository-->>Service: Entity/DTO
    Service-->>Controller: Response Data
    Controller-->>Client: HTTP Response

Loading

🔐 Permission System

The advanced permission system supports context-aware access control:

graph TD
    subgraph "Permission Structure"
        P[Permission]
        P --> R[Resource]
        P --> A[Action]
        P --> C[Context]

        R --> |examples| R1[users]
        R --> |examples| R2[files]
        R --> |examples| R3[permissions]

        A --> |examples| A1[create]
        A --> |examples| A2[read]
        A --> |examples| A3[update]
        A --> |examples| A4[delete]
        A --> |examples| A5[list]

        C --> |examples| C1[own - Own resources only]
        C --> |examples| C2[any - Any resource]
        C --> |examples| C3[team - Team resources]
        C --> |examples| C4[department - Department resources]
    end

Loading

Role Hierarchy & Inheritance

ROOT
├── ADMIN (inherits all ROOT permissions)
│   ├── USER (inherits basic ADMIN permissions)
│   │   └── GUEST (inherits limited USER permissions)
│   └── EDITOR (inherits content ADMIN permissions)
       └── USER (inherits from EDITOR)

Context Examples

• users.update.own - Can only update own profile
• users.update.any - Can update any user
• files.delete.team - Can delete files from team members
• reports.read.department - Can read reports from own department

📥 Insomnia Collection

Get the complete API collection for Insomnia: Download

📝 License

This project is under the MIT license. MIT ❤️

Liked? Leave a little star to help the project ⭐

© 2017-present Maia