Skip to Content
Developer GuideArchitecture Overview

Last Updated: 3/16/2026

Architecture Overview

LinkAce is a self-hosted bookmark management application built with modern web technologies and following Laravel best practices.

Technology Stack

Backend

  • Framework: Laravel 10.x (PHP 8.1+)
  • Database: MySQL, PostgreSQL, SQLite, or SQL Server
  • Authentication: Laravel Fortify + Sanctum
  • Queue: Database, Redis, or sync
  • Cache: File, Redis, or Memcached
  • Storage: Local filesystem or S3-compatible

Frontend

  • Build Tool: Laravel Mix (Webpack)
  • CSS Framework: Bootstrap-based custom theme
  • JavaScript: Vanilla JS with web components
  • Icons: Custom SVG icon set

Infrastructure

  • Container: Docker + Docker Compose
  • Web Server: Nginx (in Docker) or Apache/Nginx (standalone)
  • PHP: PHP-FPM 8.1+
  • Process Manager: Supervisor (for queue workers)

Application Structure

linkace/
├── app/
│   ├── Actions/           # Business logic actions
│   ├── Audits/            # Audit trail modifiers
│   ├── Console/           # CLI commands
│   ├── Enums/             # Enumerations
│   ├── Exceptions/        # Custom exceptions
│   ├── Helper/            # Helper functions
│   ├── Http/
│   │   ├── Controllers/   # Web & API controllers
│   │   ├── Middleware/    # HTTP middleware
│   │   └── Requests/      # Form request validation
│   ├── Jobs/              # Queued jobs
│   ├── Listeners/         # Event listeners
│   ├── Mail/              # Email templates
│   ├── Models/            # Eloquent models
│   ├── Notifications/     # User notifications
│   ├── Policies/          # Authorization policies
│   ├── Providers/         # Service providers
│   ├── Repositories/      # Data access layer
│   ├── Rules/             # Validation rules
│   ├── Scopes/            # Query scopes
│   ├── Settings/          # User/system settings
│   └── View/              # View composers
├── bootstrap/             # Application bootstrap
├── config/                # Configuration files
├── database/
│   ├── factories/         # Model factories
│   ├── migrations/        # Database migrations
│   └── seeders/           # Database seeders
├── lang/                  # Translations
├── public/                # Web root
├── resources/
│   ├── assets/            # Frontend assets (CSS, JS)
│   └── views/             # Blade templates
├── routes/
│   ├── api.php            # API routes
│   ├── web.php            # Web routes
│   └── channels.php       # Broadcast channels
├── storage/               # Application storage
│   ├── app/               # Application files
│   ├── framework/         # Framework files
│   └── logs/              # Application logs
├── tests/                 # Automated tests
└── deploy/                # Deployment configurations

Design Patterns

Repository Pattern

LinkAce uses the Repository pattern to abstract data access logic.

Location: app/Repositories/

Example: LinkRepository

  • create($data) - Create new link
  • update($link, $data) - Update existing link
  • delete($link) - Delete link

Benefits:

  • Separates business logic from data access
  • Makes testing easier
  • Provides consistent interface

Action Classes

Complex business operations are encapsulated in Action classes.

Location: app/Actions/

Examples:

  • Link creation with metadata fetching
  • Bulk operations
  • Import/export operations

Policy-Based Authorization

Authorization is handled through Laravel Policies.

Location: app/Policies/

Policies:

  • LinkPolicy - Link access control
  • ListPolicy - List access control
  • TagPolicy - Tag access control

Event-Driven Architecture

LinkAce uses events and listeners for decoupled features.

Events:

  • Link created → Trigger Internet Archive backup
  • Link updated → Update search index
  • User registered → Send welcome email

Data Flow

Web Request Flow

1. User Request
   ↓
2. Routing (routes/web.php)
   ↓
3. Middleware (auth, csrf, etc.)
   ↓
4. Controller (app/Http/Controllers/)
   ↓
5. Repository/Action (business logic)
   ↓
6. Model (Eloquent ORM)
   ↓
7. Database
   ↓
8. View (Blade template)
   ↓
9. Response

API Request Flow

1. API Request
   ↓
2. Routing (routes/api.php)
   ↓
3. Middleware (auth:sanctum, throttle)
   ↓
4. API Controller (app/Http/Controllers/API/)
   ↓
5. Form Request Validation
   ↓
6. Repository (business logic)
   ↓
7. Model (Eloquent ORM)
   ↓
8. Database
   ↓
9. JSON Response

Key Components

Authentication System

  • Web Auth: Session-based via Laravel Fortify
  • API Auth: Token-based via Laravel Sanctum
  • SSO: OAuth/OIDC via Socialite
  • 2FA: Time-based one-time passwords (TOTP)
  1. URL Validation - Verify URL format
  2. Metadata Fetching - Extract title, description, icon
  3. Duplicate Detection - Check for existing URLs
  4. Storage - Save to database
  5. Archival - Queue Internet Archive backup
  6. Notification - Notify user of completion

Job: app/Jobs/CheckLinks.php

  1. Scheduled task runs periodically
  2. Fetches links due for checking
  3. Sends HTTP request to each URL
  4. Updates status (OK, Moved, Broken)
  5. Notifies user of broken links

Search System

Controller: app/Http/Controllers/API/SearchController.php

  • Full-text search across links, lists, tags
  • Filters: visibility, date range, user
  • Ordering: relevance, date, title
  • Pagination support

Database Schema

Core Tables

  • users - User accounts
  • links - Bookmarked URLs
  • lists - Link collections
  • tags - Link categories
  • notes - Link annotations

Pivot Tables

  • link_lists - Link-to-List relationships
  • link_tags - Link-to-Tag relationships

System Tables

  • settings - User and system settings
  • api_tokens - API authentication tokens
  • audits - Audit trail
  • jobs - Queued jobs
  • failed_jobs - Failed queue jobs

Caching Strategy

Cache Layers

  1. Configuration Cache - config:cache
  2. Route Cache - route:cache
  3. View Cache - Compiled Blade templates
  4. Application Cache - User settings, metadata

Cache Keys

  • settings.user.{id} - User settings
  • settings.system - System settings
  • link.metadata.{url_hash} - URL metadata

Queue System

Jobs

  • SaveLinkToWaybackmachine - Archive link
  • CheckLinks - Health check links
  • ProcessImport - Import bookmarks
  • SendNotification - Send user notifications

Queue Workers

php artisan queue:work --queue=default,high,low

Security Features

Input Validation

  • Form Request classes validate all user input
  • XSS protection via Blade escaping
  • CSRF protection on all forms
  • SQL injection prevention via Eloquent ORM

Access Control

  • Row-level security via policies
  • Visibility scopes (private, internal, public)
  • API token abilities for granular permissions

Data Protection

  • Password hashing via bcrypt
  • API token encryption
  • Sensitive data masking in logs
  • Soft deletes for data recovery

Performance Optimization

Database

  • Indexed columns for common queries
  • Eager loading to prevent N+1 queries
  • Query result caching
  • Database connection pooling

Frontend

  • Asset bundling and minification
  • Lazy loading of images
  • Debounced search inputs
  • Pagination for large datasets

Caching

  • Configuration and route caching
  • View compilation
  • Database query caching
  • HTTP response caching

Deployment Architecture

Docker Deployment

┌─────────────────────────────────────┐
│         Reverse Proxy (Nginx)       │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Application (PHP-FPM)       │
│         + Queue Worker              │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Database (MySQL/PostgreSQL) │
└─────────────────────────────────────┘

Standalone Deployment

┌─────────────────────────────────────┐
│    Web Server (Apache/Nginx)        │
│    + PHP-FPM                         │
│    + Supervisor (Queue Worker)      │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Database Server              │
└─────────────────────────────────────┘

Monitoring & Logging

Logs

  • Application Logs: storage/logs/laravel.log
  • Web Server Logs: Nginx/Apache access and error logs
  • Queue Logs: Worker output and failures

Monitoring

  • Failed jobs table for queue monitoring
  • Audit trail for user actions
  • Link health status tracking
  • System health checks

Extensibility

Custom Providers

Add custom service providers in app/Providers/

Custom Commands

Create CLI commands in app/Console/Commands/

Custom Middleware

Add middleware in app/Http/Middleware/

Hooks & Events

Listen to events for custom behavior:

  • Link created/updated/deleted
  • User registered/logged in
  • Import completed

Next Steps

Data Models