# authcompanion/authcompanion2 architecture

> Architecture diagram of the GitHub repository authcompanion/authcompanion2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/authcompanion/authcompanion2
- Repository: https://github.com/authcompanion/authcompanion2

## Overview

##### Main System Components

a) Client Layer:
- Web Forms (Authentication UI)
- Admin Dashboard UI
- Two distinct client interfaces (/auth and /admin directories)

b) API Layer:
- Authentication API endpoints
- Admin API endpoints
- WebAuthn services

c) Service Layer:
- Authentication Services
- Admin Services
- WebAuthn Services

d) Data Layer:
- Database (showing both PostgreSQL and SQLite support)
- Schema management

##### Component Relationships

**[Client Layer]**
- ↓↑
**[API Routes Layer (auth.routes.js, admin.routes.js, ui.routes.js)]**
- ↓↑
**[Service Layer]**
- ↓↑
**[Data Access Layer]**

##### Specific Implementation Details

- Blue: Client-facing components
- Green: API/Route handlers
- Yellow: Service layer components
- Red: Security components (JWT, WebAuthn)
- Purple: Database components

##### Key Architectural Elements

Specific components:
**┌─ Authentication Flow ─────┐    ┌─ Admin Flow ──────────┐**
- Login                   │    │ - User Management     │
- Registration           │    │ - Admin Dashboard     │
- Profile Management     │    │ - User CRUD Ops       │
- Account Recovery       │    └─────────────────────┘
- ┘

**┌─ Security Layer ──────────┐    ┌─ Database Layer ────────┐**
- JWT Management         │    │ - PostgreSQL           │
- WebAuthn              │    │ - SQLite               │
- Cookie Handling       │    │ - Schema Management    │
- ┘    └─────────────────────────┘

##### Important Flows to Highlight

a) Authentication Flows:
- Traditional Login (username/password)
- Passwordless (WebAuthn)
- Account Recovery
- Token Refresh

b) Admin Flows:
- User Management Operations
- Dashboard Access
- Administrative Actions

##### Integration Points

External integration points:
- Email Service Integration
- JWT Token Usage
- WebAuthn Device Integration

##### Technical Details

Annotations for:
- Node.js Runtime Environment
- FastifyJS Framework (implied by the structure)
- JWT Token Flow
- Database Connections
- WebAuthn Integration

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Layer"]
        direction TB
        AuthUI["Authentication UI"]:::frontend
        AdminUI["Admin UI"]:::frontend
        
        subgraph AuthPages["Auth Pages"]
            Login["Login Page"]:::frontend
            Register["Registration Page"]:::frontend
            Profile["Profile Page"]:::frontend
            Recovery["Account Recovery"]:::frontend
        end
        
        subgraph AdminPages["Admin Pages"]
            AdminDash["Admin Dashboard"]:::frontend
            AdminLogin["Admin Login"]:::frontend
        end
        
        AuthUI --> AuthPages
        AdminUI --> AdminPages
    end
    
    subgraph API["API Routes Layer"]
        direction TB
        AuthRoutes["Auth Routes"]:::api
        AdminRoutes["Admin Routes"]:::api
        UIRoutes["UI Routes"]:::api
    end
    
    subgraph Services["Service Layer"]
        direction TB
        AuthServices["Authentication Services"]:::service
        AdminServices["Admin Services"]:::service
        WebAuthnServices["WebAuthn Services"]:::service
        
        subgraph AuthServiceDetails["Auth Services"]
            LoginSvc["Login Service"]:::service
            RegSvc["Registration Service"]:::service
            ProfileSvc["Profile Service"]:::service
            RecoverySvc["Recovery Service"]:::service
            RefreshSvc["Refresh Service"]:::service
        end
        
        subgraph AdminServiceDetails["Admin Services"]
            UserCreate["User Creation"]:::service
            UserDelete["User Deletion"]:::service
            UserList["User Listing"]:::service
            AdminLoginSvc["Admin Login"]:::service
            UserUpdate["User Updates"]:::service
        end
        
        subgraph WebAuthnDetails["WebAuthn Services"]
            LoginOpt["Login Options"]:::security
            LoginVerify["Login Verification"]:::security
            RegOpt["Registration Options"]:::security
            RegVerify["Registration Verification"]:::security
        end
    end
    
    subgraph Security["Security Layer"]
        JWT["JWT Management"]:::security
        WebAuthn["WebAuthn"]:::security
        Cookies["Cookie Handling"]:::security
        Credentials["Credential Management"]:::security
    end
    
    subgraph Data["Database Layer"]
        Postgres[(PostgreSQL)]:::database
        SQLite[(SQLite)]:::database
        Schema["Schema Management"]:::database
    end
    
    Client --> API
    API --> Services
    Services --> Security
    Services --> Data
    
    %% Component Mappings
    click AuthUI "https://github.com/authcompanion/authcompanion2/tree/main/client/auth/"
    click AdminUI "https://github.com/authcompanion/authcompanion2/tree/main/client/admin/"
    click Login "https://github.com/authcompanion/authcompanion2/blob/main/client/auth/loginPage.html"
    click Register "https://github.com/authcompanion/authcompanion2/blob/main/client/auth/registrationPage.html"
    click Profile "https://github.com/authcompanion/authcompanion2/blob/main/client/auth/profilePage.html"
    click Recovery "https://github.com/authcompanion/authcompanion2/blob/main/client/auth/recoveryPage.html"
    click AdminDash "https://github.com/authcompanion/authcompanion2/blob/main/client/admin/dashboardPage.html"
    click AdminLogin "https://github.com/authcompanion/authcompanion2/blob/main/client/admin/loginAdminPage.html"
    click AuthRoutes "https://github.com/authcompanion/authcompanion2/blob/main/routes/auth.routes.js"
    click AdminRoutes "https://github.com/authcompanion/authcompanion2/blob/main/routes/admin.routes.js"
    click UIRoutes "https://github.com/authcompanion/authcompanion2/blob/main/routes/ui.routes.js"
    click LoginSvc "https://github.com/authcompanion/authcompanion2/blob/main/services/auth/login.js"
    click RegSvc "https://github.com/authcompanion/authcompanion2/blob/main/services/auth/registration.js"
    click ProfileSvc "https://github.com/authcompanion/authcompanion2/blob/main/services/auth/profile.js"
    click RecoverySvc "https://github.com/authcompanion/authcompanion2/blob/main/services/auth/recovery.js"
    click RefreshSvc "https://github.com/authcompanion/authcompanion2/blob/main/services/auth/refresh.js"
    click UserCreate "https://github.com/authcompanion/authcompanion2/blob/main/services/admin/users/create.js"
    click UserDelete "https://github.com/authcompanion/authcompanion2/blob/main/services/admin/users/delete.js"
    click UserList "https://github.com/authcompanion/authcompanion2/blob/main/services/admin/users/list.js"
    click AdminLoginSvc "https://github.com/authcompanion/authcompanion2/blob/main/services/admin/users/login.js"
    click UserUpdate "https://github.com/authcompanion/authcompanion2/blob/main/services/admin/users/update.js"
    click LoginOpt "https://github.com/authcompanion/authcompanion2/blob/main/services/webAuthn/loginOptions.js"
    click LoginVerify "https://github.com/authcompanion/authcompanion2/blob/main/services/webAuthn/loginVerification.js"
    click RegOpt "https://github.com/authcompanion/authcompanion2/blob/main/services/webAuthn/registrationOptions.js"
    click RegVerify "https://github.com/authcompanion/authcompanion2/blob/main/services/webAuthn/registrationVerification.js"
    click JWT "https://github.com/authcompanion/authcompanion2/blob/main/utils/jwt.js"
    click Cookies "https://github.com/authcompanion/authcompanion2/blob/main/utils/cookies.js"
    click Credentials "https://github.com/authcompanion/authcompanion2/blob/main/utils/credential.js"
    click Postgres "https://github.com/authcompanion/authcompanion2/tree/main/db/postgres/"
    click SQLite "https://github.com/authcompanion/authcompanion2/tree/main/db/sqlite/"
    click Schema "https://github.com/authcompanion/authcompanion2/blob/main/db/db.js"
    
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef api fill:#2ecc71,stroke:#27ae60,color:white
    classDef service fill:#f1c40f,stroke:#f39c12,color:black
    classDef security fill:#e74c3c,stroke:#c0392b,color:white
    classDef database fill:#9b59b6,stroke:#8e44ad,color:white
```
