Skip to Content
Technical ReferenceArchitecture Overview

Last Updated: 3/13/2026

Architecture Overview

LinkAce is a self-hosted bookmark manager built with Laravel 11, designed to run in Docker containers or as a traditional PHP application.

Technology Stack

Backend

  • Framework: Laravel 11.48
  • Language: PHP 8.2+
  • Database: MySQL, PostgreSQL, SQLite, or SQL Server
  • Cache/Queue: Redis (optional)
  • Search: Database-based full-text search

Frontend

  • Build Tool: Laravel Mix (webpack)
  • CSS Framework: Bootstrap (implied by UI components)
  • JavaScript: Vanilla JS with web components (e.g., <time-ago>)
  • Icons: Custom icon components

Infrastructure

  • Containerization: Docker + Docker Compose
  • Web Server: nginx (in Docker) or Apache/nginx (traditional)
  • Process Manager: Supervisor (for queue workers)

Application Architecture

LinkAce follows Laravel’s MVC architecture with additional layers:

┌─────────────────────────────────────────────────┐
│                   HTTP Layer                     │
│  (Routes, Middleware, Controllers)              │
└─────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────┐
│              Business Logic Layer               │
│  (Actions, Repositories, Services)              │
└─────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────┐
│                  Data Layer                     │
│  (Models, Database, Eloquent ORM)               │
└─────────────────────────────────────────────────┘

Directory Structure

app/
├── Actions/          # Business logic actions
├── Audits/           # Audit trail modifiers
├── Console/          # Artisan commands
├── Enums/            # Enumerations and constants
├── Exceptions/       # Custom exception handlers
├── Helper/           # Helper functions
├── Http/
│   ├── Controllers/  # HTTP controllers
│   │   ├── API/      # API endpoints
│   │   ├── Admin/    # Admin panel
│   │   ├── App/      # Main application
│   │   └── Guest/    # Public/guest features
│   ├── Middleware/   # HTTP middleware
│   └── Requests/     # Form requests
├── Jobs/             # Queue jobs
├── Listeners/        # Event listeners
├── Mail/             # Email templates
├── Models/           # Eloquent models
├── Notifications/    # Notification classes
├── Policies/         # Authorization policies
├── Providers/        # Service providers
├── Repositories/     # Data repositories
├── Rules/            # Custom validation rules
├── Scopes/           # Query scopes
├── Settings/         # Application settings
└── View/             # View composers

config/               # Configuration files
database/
├── factories/        # Model factories
├── migrations/       # Database migrations
└── seeders/          # Database seeders

resources/
├── lang/             # Translations
└── views/            # Blade templates

routes/
├── api.php           # API routes
├── channels.php      # Broadcasting channels
└── web.php           # Web routes

storage/              # File storage, logs, cache
tests/                # PHPUnit tests

Key Components

1. Actions Pattern

LinkAce uses the Action pattern to encapsulate business logic:

Location: app/Actions/

Purpose: Single-responsibility classes that perform specific operations.

Example Actions:

  • Link creation
  • Bookmark import/export
  • Link checking
  • Backup operations

2. Repositories

Data access is abstracted through repository classes:

Location: app/Repositories/

Purpose: Centralize database queries and provide a clean API for data access.

3. Jobs & Queues

Asynchronous tasks are handled through Laravel’s queue system:

Location: app/Jobs/

Key Jobs:

  • SaveLinkToWaybackmachine - Archive links on Internet Archive
  • Link checking jobs
  • Backup jobs
  • Email sending

Queue Configuration:

  • Driver: Redis (recommended) or database
  • Workers managed by Supervisor

4. Events & Listeners

Event-driven architecture for decoupled components:

Location: app/Listeners/

Purpose: React to application events (link created, user registered, etc.)

5. Middleware

HTTP middleware for cross-cutting concerns:

Common Middleware:

  • Authentication (auth, auth:sanctum)
  • Rate limiting (throttle)
  • CSRF protection
  • Role/permission checks

6. Service Providers

Laravel service providers bootstrap application services:

Location: app/Providers/

Key Providers:

  • AppServiceProvider - Application-level services
  • AuthServiceProvider - Authentication & authorization
  • EventServiceProvider - Event listeners
  • RouteServiceProvider - Route configuration

Data Flow

Web Request Flow

1. HTTP Request
   ↓
2. Routing (routes/web.php)
   ↓
3. Middleware (auth, CSRF, etc.)
   ↓
4. Controller (app/Http/Controllers/)
   ↓
5. Action/Repository (app/Actions/, app/Repositories/)
   ↓
6. Model (app/Models/)
   ↓
7. Database
   ↓
8. View (resources/views/)
   ↓
9. HTTP Response

API Request Flow

1. HTTP Request
   ↓
2. Routing (routes/api.php)
   ↓
3. Middleware (auth:sanctum, throttle)
   ↓
4. API Controller (app/Http/Controllers/API/)
   ↓
5. Action/Repository
   ↓
6. Model
   ↓
7. Database
   ↓
8. JSON Response

Database Design

Core Tables

  • users - User accounts
  • links - Bookmarked URLs
  • link_lists - Bookmark collections
  • tags - Tagging system
  • notes - Link annotations
  • link_lists (pivot) - Link-to-list relationships
  • link_tags (pivot) - Link-to-tag relationships

System Tables

  • personal_access_tokens - API tokens
  • password_resets - Password reset tokens
  • failed_jobs - Failed queue jobs
  • audits - Audit trail
  • activity_log - Activity logging
  • settings - Application settings
  • roles - User roles
  • permissions - User permissions
  • model_has_roles - User-role assignments
  • model_has_permissions - User-permission assignments
  • role_has_permissions - Role-permission assignments

Soft Deletes

Most models use soft deletes (trash functionality):

  • Links
  • Lists
  • Tags
  • Notes
  • Users

Soft-deleted records can be restored or permanently deleted.

External Integrations

1. Internet Archive (Wayback Machine)

LinkAce can automatically archive bookmarks to the Internet Archive.

Job: SaveLinkToWaybackmachine

Configuration:

  • archive_backups_enabled - Enable/disable archiving
  • archive_private_backups_enabled - Archive private links

2. Email Services

Supports multiple email providers via Laravel’s mail system:

Supported Drivers:

  • SMTP
  • Mailgun (via symfony/mailgun-mailer)
  • SendGrid
  • Amazon SES
  • Postmark

Configuration: .env file and config/mail.php

3. Backup Services

Automatic backups via spatie/laravel-backup:

Supported Destinations:

  • Local filesystem
  • Amazon S3 (via league/flysystem-aws-s3-v3)
  • FTP (via league/flysystem-ftp)
  • SFTP (via league/flysystem-sftp-v3)

4. OAuth/OIDC Providers

SSO integration via Laravel Socialite:

Package: laravel/socialite + provider packages

Providers:

  • Auth0, Authentik, Azure, Cognito, FusionAuth, Google, GitHub, GitLab, Keycloak, OIDC, Okta, Zitadel

5. Monitoring & Error Tracking

Sentry Integration:

  • Package: sentry/sentry-laravel
  • Automatic error reporting and performance monitoring

Security Architecture

Authentication Layers

  1. Session-based (Web): Laravel Fortify + session guard
  2. Token-based (API): Laravel Sanctum
  3. SSO (OAuth/OIDC): Laravel Socialite

Authorization Layers

  1. Policies: Model-level authorization
  2. Roles & Permissions: Spatie Laravel Permission
  3. Visibility Scopes: Automatic query filtering

Data Protection

  • Password Hashing: bcrypt
  • CSRF Protection: Token-based
  • SQL Injection Prevention: Eloquent ORM + prepared statements
  • XSS Prevention: Blade template escaping

Performance Optimization

Caching Strategy

  • Configuration Cache: php artisan config:cache
  • Route Cache: php artisan route:cache
  • View Cache: Compiled Blade templates
  • Query Cache: Redis (optional)

Database Optimization

  • Indexes: On foreign keys and frequently queried columns
  • Eager Loading: Prevent N+1 queries
  • Pagination: For large result sets

Asset Optimization

  • Laravel Mix: Asset compilation and minification
  • Versioning: Cache busting via Mix versioning

Deployment Architecture

┌─────────────────────────────────────────┐
│           Docker Compose                │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────────┐  ┌────────────────┐ │
│  │   nginx      │  │   PHP-FPM      │ │
│  │  (web server)│←→│   (LinkAce)    │ │
│  └──────────────┘  └────────────────┘ │
│         ↑                   ↓          │
│         │          ┌────────────────┐ │
│         │          │   Database     │ │
│         │          │ (MySQL/Postgres)│ │
│         │          └────────────────┘ │
│         │                   ↓          │
│         │          ┌────────────────┐ │
│         └──────────│     Redis      │ │
│                    │  (cache/queue) │ │
│                    └────────────────┘ │
└─────────────────────────────────────────┘

Docker Compose Files:

  • docker-compose.yml - Development
  • docker-compose.production.yml - Production

Traditional Deployment

┌─────────────────────────────────────────┐
│         Web Server (nginx/Apache)       │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────────────────────────────┐  │
│  │       PHP-FPM / mod_php          │  │
│  │         (LinkAce)                │  │
│  └──────────────────────────────────┘  │
│                 ↓                       │
│  ┌──────────────────────────────────┐  │
│  │         Database Server          │  │
│  │      (MySQL/Postgres/SQLite)     │  │
│  └──────────────────────────────────┘  │
│                 ↓                       │
│  ┌──────────────────────────────────┐  │
│  │      Redis (optional)            │  │
│  └──────────────────────────────────┘  │
│                                         │
│  ┌──────────────────────────────────┐  │
│  │   Supervisor (queue workers)     │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘

Configuration Management

Environment Variables

All configuration is driven by .env file:

Key Variables:

  • APP_* - Application settings
  • DB_* - Database configuration
  • MAIL_* - Email settings
  • REDIS_* - Redis configuration
  • SSO_* - SSO settings
  • BACKUP_* - Backup settings

Configuration Files

Located in config/:

  • app.php - Application settings
  • auth.php - Authentication
  • database.php - Database connections
  • mail.php - Email configuration
  • queue.php - Queue configuration
  • services.php - Third-party services

Testing

Test Structure

tests/
├── Feature/      # Feature tests (HTTP, integration)
└── Unit/         # Unit tests (isolated logic)

Test Tools

  • PHPUnit: Test framework
  • Laravel Testing: HTTP testing, database factories
  • Mockery: Mocking framework

Running Tests

./vendor/bin/phpunit
# or
php artisan test

CLI Commands

Custom Artisan Commands

Located in app/Console/Commands/:

Key Commands:

  • Link checking
  • Backup operations
  • User management
  • Database maintenance

Running Commands

php artisan linkace:check-links
php artisan linkace:backup

Monitoring & Logging

Logging

  • Driver: Stack (multiple channels)
  • Channels: Daily rotating files, Syslog, Slack, etc.
  • Location: storage/logs/

Log Viewer

Built-in log viewer via rap2hpoutre/laravel-log-viewer:

Access: Admin panel → Logs

Activity Logging

Automatic activity logging via spatie/laravel-activitylog:

  • User actions
  • Model changes
  • System events

Audit Trail

Comprehensive audit trail via owen-it/laravel-auditing:

  • Tracks all model changes
  • Stores old and new values
  • Records user, IP, and timestamp
Api ReferenceData Models