Skip to Content
Architecture Overview

Last Updated: 3/17/2026

Architecture Overview

LinkAce is a modern, self-hosted bookmark management application built with Laravel (PHP) and Vue.js. This document provides a high-level overview of the application’s architecture, components, and design patterns.

Technology Stack

Backend

  • Framework: Laravel 10.x
  • Language: PHP 8.2+
  • Database: MySQL 8.0+ / MariaDB 10.5+ / PostgreSQL 13+
  • Cache/Queue: Redis (optional)
  • API: RESTful API with Laravel Sanctum authentication

Frontend

  • Build Tool: Laravel Mix with Webpack
  • CSS Framework: Bootstrap 5
  • JavaScript: Vue.js components for interactive features
  • Package Management: npm

Deployment

  • Containerization: Docker & Docker Compose
  • Orchestration: Kubernetes (Helm charts available)
  • Server Requirements: Nginx/Apache, PHP-FPM

Application Architecture

LinkAce follows a layered architecture pattern with clear separation of concerns:

┌─────────────────────────────────────────┐
│          Presentation Layer             │
│  (Controllers, Views, API Endpoints)    │
├─────────────────────────────────────────┤
│         Application Layer               │
│    (Actions, Jobs, Repositories)        │
├─────────────────────────────────────────┤
│           Domain Layer                  │
│      (Models, Policies, Rules)          │
├─────────────────────────────────────────┤
│       Infrastructure Layer              │
│  (Database, Queue, Cache, External)     │
└─────────────────────────────────────────┘

Core Components

1. Models (app/Models/)

The domain models represent the core business entities:

  • Link: Bookmarked URLs with metadata
  • LinkList: Collections for organizing links
  • Tag: Labels for categorizing links
  • Note: Text annotations for links
  • User: User accounts and authentication

All models implement:

  • Soft Deletes: Safe deletion with trash/restore capability
  • Auditing: Complete change tracking for accountability
  • Visibility Scopes: Multi-level privacy controls
  • Relationships: Eloquent ORM for database relations

See Data Models and Database Schema for detailed model documentation.

2. Controllers (app/Http/Controllers/)

Controllers handle HTTP requests and coordinate application logic:

Web Controllers

  • Handle browser-based UI interactions
  • Return Blade views with data
  • Manage authentication, sessions, and CSRF protection

API Controllers (app/Http/Controllers/API/)

  • RESTful endpoints for programmatic access
  • JSON responses following API standards
  • Token-based authentication via Laravel Sanctum
  • Rate limiting and throttling

Key API controllers:

  • LinkController: CRUD operations for links
  • ListController: CRUD operations for lists
  • TagController: CRUD operations for tags
  • SearchController: Advanced search functionality
  • BulkEditController: Bulk operations on multiple resources
  • TrashController: Trash management and restoration

See API Reference for complete API documentation.

3. Repositories (app/Repositories/)

Repositories encapsulate complex business logic and database operations, abstracting away implementation details from controllers.

LinkRepository is the primary repository and handles:

  • Creating links with automatic metadata generation
  • Updating links and managing relationships (lists, tags)
  • Deleting links (soft delete with audit trail)
  • Duplicate detection
  • Internet Archive backup initiation

Benefits of the Repository pattern:

  • Single Responsibility: Controllers focus on HTTP, repositories handle data
  • Testability: Easy to mock repositories in tests
  • Maintainability: Business logic changes in one place
  • Reusability: Same logic used by web and API controllers

4. Actions (app/Actions/)

Actions are single-purpose classes that encapsulate specific business operations. LinkAce uses Actions for:

  • Complex multi-step processes
  • Reusable operations across different parts of the application
  • Operations that don’t fit cleanly into controllers or repositories

Examples:

  • Generating link previews from URLs
  • Processing bookmark imports from HTML files
  • Exporting bookmarks to various formats

5. Jobs (app/Jobs/)

Background jobs handle asynchronous operations using Laravel’s queue system:

SaveLinkToWaybackmachine

  • Archives links to the Internet Archive
  • Respects privacy settings (skips private links unless configured)
  • Dispatched after link creation or update
  • Runs in the background to avoid slowing down user requests

ImportLinkJob

  • Processes individual links during bulk imports
  • Handles metadata extraction and validation
  • Reports progress and errors back to the user

Benefits of background jobs:

  • Non-blocking: Users don’t wait for slow operations
  • Reliability: Failed jobs can be retried automatically
  • Scalability: Jobs can be distributed across multiple workers

6. Policies (app/Policies/)

Laravel Policies define authorization rules for model operations:

  • Check if a user can view, create, update, or delete a resource
  • Implement visibility-based access control
  • Support both ownership-based and role-based authorization

Key policies:

  • LinkPolicy: Authorization for link operations
  • ListPolicy: Authorization for list operations
  • TagPolicy: Authorization for tag operations

7. Middleware

Custom middleware handles cross-cutting concerns:

  • Authentication: Laravel Sanctum for API, session-based for web
  • Authorization: Role-based access control (admin vs. regular users)
  • Rate Limiting: API request throttling
  • Localization: Language detection and switching

8. Service Layer

Additional services provide specialized functionality:

Helper Functions (app/Helper/)

  • Utility functions for common operations
  • Date/time formatting
  • URL manipulation
  • User settings access

Settings (app/Settings/)

  • User-specific settings storage
  • System-wide configuration
  • Feature toggles

Enums (app/Enums/)

  • Type-safe constants for visibility levels, token abilities, model attributes
  • Consistent value references across the application

Data Flow

User Form Submission
    ↓
Controller validates request (LinkStoreRequest)
    ↓
LinkRepository::create()
    ├→ Extract metadata from URL
    ├→ Create Link model
    ├→ Attach Lists and Tags
    ├→ Dispatch SaveLinkToWaybackmachine job
    └→ Return created Link
    ↓
Controller redirects user
    ↓
View displays success message
API Request (JSON + Bearer Token)
    ↓
Sanctum Middleware (authenticate)
    ↓
LinkController::store()
    ↓
LinkRepository::create()
    └→ (same as web flow)
    ↓
Return JSON response
Scheduled Job (Laravel Scheduler)
    ↓
CheckLinks command
    ↓
For each link due for check:
    ├→ HTTP request to URL
    ├→ Update link status (OK, MOVED, BROKEN)
    └→ Log result
    ↓
Notification to user (optional)

Key Design Patterns

1. Repository Pattern

Abstracts data access logic from controllers.

2. Action Pattern

Encapsulates complex business logic in single-purpose classes.

3. Observer Pattern

Eloquent model observers for side effects (e.g., queuing jobs when a link is created).

4. Strategy Pattern

Different import/export strategies for various bookmark formats.

5. Soft Delete Pattern

Trash/restore functionality without permanent data loss.

Authentication & Authorization

Multi-User Support

  • Each user has their own isolated space for links, lists, and tags
  • Visibility system allows selective sharing:
    • Private: Only the owner
    • Internal: All authenticated users
    • Public: Everyone (including guests)

SSO Integration

  • OAuth 2.0 support
  • OpenID Connect (OIDC) support
  • Configurable providers (Google, GitHub, etc.)

See SSO Configuration for setup details.

API Token System

Two types of API tokens:

  • User Tokens: Scoped to individual users
  • System Tokens: Global access with special abilities

See User API Tokens and System API Tokens.

Background Processing

Queue System

LinkAce uses Laravel’s queue system for asynchronous operations:

  • Driver: Redis (recommended) or database
  • Workers: Process jobs in the background
  • Retry Logic: Automatic retry on failure
  • Monitoring: Failed job tracking

Scheduled Tasks

Laravel Scheduler runs periodic tasks:

  • Link health checks
  • Cleanup of old audit logs
  • Backup operations
  • Statistics computation

External Integrations

Internet Archive (Wayback Machine)

  • Automatic archiving of public links
  • Optional archiving of private links
  • Configurable via user settings

Zapier

  • Pre-built integration available on Zapier platform
  • Connect LinkAce with 2500+ apps
  • Trigger actions based on new links, tags, lists

Browser Integration

  • Bookmarklet for quick link saving
  • Browser extension support

Scalability Considerations

Horizontal Scaling

  • Stateless Web Tier: Multiple PHP-FPM workers behind load balancer
  • Queue Workers: Multiple workers for background job processing
  • Session Storage: Redis for distributed sessions

Database Optimization

  • Indexed fields for fast queries
  • Query scopes for efficient filtering
  • Eager loading to prevent N+1 problems
  • Pagination for large result sets

Caching Strategy

  • Query Results: Cache expensive database queries
  • Config Cache: Laravel config caching for production
  • View Cache: Blade template compilation caching

Security Features

Input Validation

  • Form Request validation classes
  • SQL injection prevention via Eloquent ORM
  • XSS prevention via Blade escaping

CSRF Protection

  • Automatic token generation for all forms
  • SameSite cookie configuration

Rate Limiting

  • API throttling to prevent abuse
  • Configurable limits per endpoint

Data Privacy

  • Soft deletes for audit trail
  • Encrypted sensitive data (passwords via bcrypt)
  • GDPR compliance features (data export, account deletion)

Testing

LinkAce includes:

  • Unit Tests: Model logic, helper functions
  • Feature Tests: HTTP requests, authentication
  • Browser Tests: End-to-end testing with Laravel Dusk

Test suite is run via PHPUnit.

Deployment Architecture

┌─────────────────────────────────────────┐
│         Reverse Proxy (Nginx)           │
│        (SSL Termination, Routing)       │
└───────────────┬─────────────────────────┘
                │
┌───────────────┴─────────────────────────┐
│          LinkAce Container              │
│   (Nginx + PHP-FPM + Application)       │
└───────────────┬─────────────────────────┘
                │
    ┌───────────┴───────────┐
    │                       │
┌───▼──────┐       ┌────────▼──────┐
│ Database │       │  Redis        │
│ Container│       │  Container    │
│ (MySQL)  │       │ (Cache/Queue) │
└──────────┘       └───────────────┘

Kubernetes Deployment

LinkAce provides official Helm charts for Kubernetes deployment with:

  • Auto-scaling capabilities
  • High availability configuration
  • Persistent volume claims for uploads
  • Health checks and readiness probes

See Setup with Helm (Kubernetes) for details.

Configuration

Configuration is managed via:

  1. Environment Variables: .env file for deployment-specific settings
  2. Config Files: Laravel config files in config/ directory
  3. Database Settings: User and system settings stored in database

Key configuration areas:

  • Database connection
  • Redis configuration
  • Mail server settings
  • OAuth providers
  • API rate limits
  • Feature toggles

See Advanced Settings for complete configuration reference.

Monitoring & Logging

Application Logs

  • Laravel’s logging system (Monolog)
  • Configurable log channels (file, syslog, etc.)
  • Debug mode for development

Audit Logs

  • Complete change history via auditing package
  • User attribution for all changes
  • Queryable audit trail

Health Checks

  • Database connectivity
  • Queue worker status
  • Disk space monitoring

Further Reading

From V1Data Models And Database Schema