# kovah/linkace architecture

> Architecture diagram of the GitHub repository kovah/linkace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kovah/linkace
- Repository: https://github.com/kovah/linkace

## Overview

LinkAce is a self-hosted bookmark archive. A user or API client enters through Laravel web/API routing, then controllers validate and dispatch bookmark, taxonomy, search, import/export, sharing, or administration actions. Repositories and Eloquent models persist results; asynchronous jobs monitor links and archive them externally. The tree and README establish additional OAuth, backup, RSS, and integration capabilities, but several route targets and implementations were not sampled, so those relationships are shown only where directory or class names provide sufficient evidence.

Main entry points: [`app/Providers/RouteServiceProvider.php`](https://github.com/kovah/linkace/blob/2.x/app/Providers/RouteServiceProvider.php) (Web API Routing), [`config/database.php`](https://github.com/kovah/linkace/blob/2.x/config/database.php) (Application Database), [`app/Repositories`](https://github.com/kovah/linkace/tree/2.x/app/Repositories) (Domain Repositories), [`app/Http/Controllers/Models/LinkController.php`](https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/Models/LinkController.php) (Link Management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application Entry"]
  node_routing["Web API Routing"]
end

subgraph group_bookmarks["Bookmark Domain"]
  node_link_ui["Link Management<br/>[LinkController.php]"]
  node_link_api["REST API"]
  node_repositories["Domain Repositories"]
  node_database[("Application Database<br/>[database.php]")]
end

subgraph group_discovery["Discovery Exchange"]
  node_search["Search Backend"]
  node_search_ui["Search Controllers"]
  node_import["Bookmark Import"]
  node_import_job["Import Job<br/>[ImportLinkJob.php]"]
  node_export["Bookmark Export"]
  node_feeds["Public RSS Feeds<br/>[FeedController.php]"]
end

subgraph group_identity["Identity Administration"]
  node_registration["User Registration<br/>[CreateNewUser.php]"]
  node_oauth["OAuth Login"]
  node_user_admin["User Administration"]
end

subgraph group_automation["Automation Integrations"]
  node_link_checker["Link Monitoring"]
  node_archive_job["Archive Job"]
  node_backup["Backup Storage<br/>[backup.php]"]
end

node_user(("User"))
node_api_client(("API Client"))
node_web(("Linked Websites"))
node_oauth_provider(("OAuth Provider"))
node_internet_archive(("Internet Archive"))
node_object_storage[("S3-Compatible Storage")]

node_user -->|"sends requests"| node_routing
node_api_client -->|"calls API"| node_routing
node_routing -->|"dispatches web"| node_link_ui
node_routing -->|"dispatches API"| node_link_api
node_routing -->|"dispatches search"| node_search_ui
node_routing -->|"dispatches import"| node_import
node_routing -->|"dispatches export"| node_export
node_routing -->|"dispatches feeds"| node_feeds
node_link_ui -->|"writes bookmarks"| node_repositories
node_link_ui -->|"reads links"| node_database
node_link_api -->|"updates models"| node_repositories
node_repositories -->|"persists data"| node_database
node_search_ui -->|"runs search"| node_search
node_search -->|"queries links"| node_database
node_import -->|"queues imports"| node_import_job
node_import_job -->|"creates links"| node_repositories
node_export -->|"reads bookmarks"| node_database
node_feeds -->|"reads public data"| node_database
node_user -->|"registers account"| node_registration
node_registration -->|"creates user"| node_database
node_user -->|"starts login"| node_oauth
node_oauth -.->|"authenticates"| node_oauth_provider
node_user_admin -->|"manages users"| node_database
node_link_checker -->|"updates status"| node_database
node_link_checker -->|"checks links"| node_web
node_archive_job -.->|"archives links"| node_internet_archive
node_backup -.->|"stores backups"| node_object_storage

click node_routing "https://github.com/kovah/linkace/blob/2.x/app/Providers/RouteServiceProvider.php"
click node_link_ui "https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/Models/LinkController.php"
click node_link_api "https://github.com/kovah/linkace/tree/2.x/app/Http/Controllers/API"
click node_repositories "https://github.com/kovah/linkace/tree/2.x/app/Repositories"
click node_database "https://github.com/kovah/linkace/blob/2.x/config/database.php"
click node_search "https://github.com/kovah/linkace/blob/2.x/app/Search/SearchBackendManager.php"
click node_search_ui "https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/App/SearchController.php"
click node_import "https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/App/ImportController.php"
click node_import_job "https://github.com/kovah/linkace/blob/2.x/app/Jobs/ImportLinkJob.php"
click node_export "https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/App/ExportController.php"
click node_feeds "https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/Guest/FeedController.php"
click node_registration "https://github.com/kovah/linkace/blob/2.x/app/Actions/Fortify/CreateNewUser.php"
click node_oauth "https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/SocialiteController.php"
click node_user_admin "https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/Admin/UserManagementController.php"
click node_link_checker "https://github.com/kovah/linkace/blob/2.x/app/Console/Commands/CheckLinksCommand.php"
click node_archive_job "https://github.com/kovah/linkace/blob/2.x/app/Jobs/SaveLinkToWaybackmachine.php"
click node_backup "https://github.com/kovah/linkace/blob/2.x/config/backup.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routing,node_user,node_api_client toneBlue
class node_link_ui,node_link_api,node_repositories,node_database,node_object_storage toneAmber
class node_search,node_search_ui,node_import,node_import_job,node_export,node_feeds toneMint
class node_registration,node_oauth,node_user_admin toneRose
class node_link_checker,node_archive_job,node_backup,node_web,node_oauth_provider,node_internet_archive toneIndigo
```

## Components

### Application Entry

- [Web API Routing](https://github.com/kovah/linkace/blob/2.x/app/Providers/RouteServiceProvider.php): `app/Providers/RouteServiceProvider.php`

### Bookmark Domain

- [Link Management](https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/Models/LinkController.php): `app/Http/Controllers/Models/LinkController.php`
- [REST API](https://github.com/kovah/linkace/tree/2.x/app/Http/Controllers/API): `app/Http/Controllers/API`
- [Domain Repositories](https://github.com/kovah/linkace/tree/2.x/app/Repositories): `app/Repositories`
- [Application Database](https://github.com/kovah/linkace/blob/2.x/config/database.php): `config/database.php`

### Discovery Exchange

- [Search Backend](https://github.com/kovah/linkace/blob/2.x/app/Search/SearchBackendManager.php): `app/Search/SearchBackendManager.php`
- [Search Controllers](https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/App/SearchController.php): `app/Http/Controllers/App/SearchController.php`
- [Bookmark Import](https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/App/ImportController.php): `app/Http/Controllers/App/ImportController.php`
- [Import Job](https://github.com/kovah/linkace/blob/2.x/app/Jobs/ImportLinkJob.php): `app/Jobs/ImportLinkJob.php`
- [Bookmark Export](https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/App/ExportController.php): `app/Http/Controllers/App/ExportController.php`
- [Public RSS Feeds](https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/Guest/FeedController.php): `app/Http/Controllers/Guest/FeedController.php`

### Identity Administration

- [User Registration](https://github.com/kovah/linkace/blob/2.x/app/Actions/Fortify/CreateNewUser.php): `app/Actions/Fortify/CreateNewUser.php`
- [OAuth Login](https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/SocialiteController.php): `app/Http/Controllers/SocialiteController.php`
- [User Administration](https://github.com/kovah/linkace/blob/2.x/app/Http/Controllers/Admin/UserManagementController.php): `app/Http/Controllers/Admin/UserManagementController.php`

### Automation Integrations

- [Link Monitoring](https://github.com/kovah/linkace/blob/2.x/app/Console/Commands/CheckLinksCommand.php): `app/Console/Commands/CheckLinksCommand.php`
- [Archive Job](https://github.com/kovah/linkace/blob/2.x/app/Jobs/SaveLinkToWaybackmachine.php): `app/Jobs/SaveLinkToWaybackmachine.php`
- [Backup Storage](https://github.com/kovah/linkace/blob/2.x/config/backup.php): `config/backup.php`

### Other components

- **User**
- **API Client**
- **Linked Websites**
- **OAuth Provider**
- **Internet Archive**
- **S3-Compatible Storage**

## Connections

- User → Web API Routing: sends requests
- API Client → Web API Routing: calls API
- Web API Routing → Link Management: dispatches web
- Web API Routing → REST API: dispatches API
- Web API Routing → Search Controllers: dispatches search
- Web API Routing → Bookmark Import: dispatches import
- Web API Routing → Bookmark Export: dispatches export
- Web API Routing → Public RSS Feeds: dispatches feeds
- Link Management → Domain Repositories: writes bookmarks
- Link Management → Application Database: reads links
- REST API → Domain Repositories: updates models
- Domain Repositories → Application Database: persists data
- Search Controllers → Search Backend: runs search
- Search Backend → Application Database: queries links
- Bookmark Import → Import Job: queues imports
- Import Job → Domain Repositories: creates links
- Bookmark Export → Application Database: reads bookmarks
- Public RSS Feeds → Application Database: reads public data
- User → User Registration: registers account
- User Registration → Application Database: creates user
- User → OAuth Login: starts login
- OAuth Login → OAuth Provider: authenticates
- User Administration → Application Database: manages users
- Link Monitoring → Application Database: updates status
- Link Monitoring → Linked Websites: checks links
- Archive Job → Internet Archive: archives links
- Backup Storage → S3-Compatible Storage: stores backups
