# allaingaye/url-shortener architecture

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

- Interactive diagram: https://gitdiagram.com/allaingaye/url-shortener
- Repository: https://github.com/allaingaye/url-shortener

## Overview

This Laravel URL-shortener API handles account/token workflows, URL creation and management, public redirects, and click analytics. A redirect resolves an active, unexpired code through the URL service, increments its counter, queues detailed click capture, and returns a 302. The README also documents rate limiting, security headers, API documentation, and daily expiration pruning. Source excerpts establish the main redirect and asynchronous analytics calls; several API routes and integrations are represented only by README statements or the source index, so uncertain implementation links are omitted.

Main entry points: [`routes/api.php`](https://github.com/allaingaye/url-shortener/blob/main/routes/api.php) (API routes), [`app/Http/Controllers/Api/UrlController.php`](https://github.com/allaingaye/url-shortener/blob/main/app/Http/Controllers/Api/UrlController.php) (URL management), [`app/Http/Controllers/RedirectController.php`](https://github.com/allaingaye/url-shortener/blob/main/app/Http/Controllers/RedirectController.php) (Redirect handler), [`app/Services/UrlService.php`](https://github.com/allaingaye/url-shortener/blob/main/app/Services/UrlService.php) (URL service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_api_routes["API routes<br/>[api.php]"]
  node_auth["Account and tokens<br/>[AuthController.php]"]
  node_user["User accounts<br/>[User.php]"]
  node_policy["URL ownership policy<br/>[UrlPolicy.php]"]
end

subgraph group_links["Link lifecycle"]
  node_url_api["URL management<br/>[UrlController.php]"]
  node_url_requests["URL validation"]
  node_url_service["URL service<br/>[UrlService.php]"]
  node_code_generator["Code generator"]
  node_url_model[("URL records<br/>[Url.php]")]
  node_url_resource["URL response<br/>[UrlResource.php]"]
  node_redirect_route["Redirect route<br/>[web.php]"]
  node_redirect["Redirect handler"]
  node_prune["Expired URL pruning"]
end

subgraph group_analytics["Click analytics"]
  node_click_job["Click job<br/>[RecordClick.php]"]
  node_analytics_service["Analytics capture"]
  node_click_model[("Click records<br/>[Click.php]")]
  node_stats["Analytics endpoint"]
end

subgraph group_platform["Runtime safeguards"]
  node_security["Security headers"]
  node_rate_limits["Rate limiting<br/>[api.php]"]
  node_api_docs["OpenAPI documentation<br/>[OpenApi.php]"]
end

node_client(("API client"))
node_visitor(("Link visitor"))

node_client -->|"calls API"| node_api_routes
node_api_routes -->|"routes auth"| node_auth
node_auth -->|"creates and authenticates"| node_user
node_api_routes -->|"routes URL operations"| node_url_api
node_url_api -->|"validates input"| node_url_requests
node_url_api -->|"delegates URL actions"| node_url_service
node_url_service -->|"generates codes"| node_code_generator
node_url_service -->|"creates and resolves"| node_url_model
node_url_api -->|"formats responses"| node_url_resource
node_url_api -.->|"authorizes ownership"| node_policy
node_visitor -->|"requests short link"| node_redirect_route
node_redirect_route -->|"dispatches redirect"| node_redirect
node_redirect -->|"resolves code"| node_url_service
node_redirect -->|"increments clicks"| node_url_model
node_redirect -->|"dispatches click"| node_click_job
node_click_job -->|"records event"| node_analytics_service
node_analytics_service -->|"persists click details"| node_click_model
node_api_routes -->|"routes statistics"| node_stats
node_stats -->|"aggregates click data"| node_click_model
node_stats -.->|"checks URL ownership"| node_policy
node_prune -->|"prunes expired URLs"| node_url_model
node_security -.->|"protects requests"| node_api_routes
node_rate_limits -.->|"limits requests"| node_api_routes
node_api_docs -.->|"documents API"| node_client

click node_api_routes "https://github.com/allaingaye/url-shortener/blob/main/routes/api.php"
click node_auth "https://github.com/allaingaye/url-shortener/blob/main/app/Http/Controllers/Api/AuthController.php"
click node_user "https://github.com/allaingaye/url-shortener/blob/main/app/Models/User.php"
click node_url_api "https://github.com/allaingaye/url-shortener/blob/main/app/Http/Controllers/Api/UrlController.php"
click node_url_requests "https://github.com/allaingaye/url-shortener/tree/main/app/Http/Requests"
click node_url_service "https://github.com/allaingaye/url-shortener/blob/main/app/Services/UrlService.php"
click node_code_generator "https://github.com/allaingaye/url-shortener/blob/main/app/Services/ShortCodeGenerator.php"
click node_url_model "https://github.com/allaingaye/url-shortener/blob/main/app/Models/Url.php"
click node_url_resource "https://github.com/allaingaye/url-shortener/blob/main/app/Http/Resources/UrlResource.php"
click node_redirect_route "https://github.com/allaingaye/url-shortener/blob/main/routes/web.php"
click node_redirect "https://github.com/allaingaye/url-shortener/blob/main/app/Http/Controllers/RedirectController.php"
click node_click_job "https://github.com/allaingaye/url-shortener/blob/main/app/Jobs/RecordClick.php"
click node_analytics_service "https://github.com/allaingaye/url-shortener/blob/main/app/Services/AnalyticsService.php"
click node_click_model "https://github.com/allaingaye/url-shortener/blob/main/app/Models/Click.php"
click node_stats "https://github.com/allaingaye/url-shortener/blob/main/app/Http/Controllers/Api/UrlStatsController.php"
click node_policy "https://github.com/allaingaye/url-shortener/blob/main/app/Policies/UrlPolicy.php"
click node_prune "https://github.com/allaingaye/url-shortener/blob/main/app/Console/Commands/PruneExpiredUrls.php"
click node_security "https://github.com/allaingaye/url-shortener/blob/main/app/Http/Middleware/SecurityHeaders.php"
click node_rate_limits "https://github.com/allaingaye/url-shortener/blob/main/routes/api.php"
click node_api_docs "https://github.com/allaingaye/url-shortener/blob/main/app/OpenApi/OpenApi.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_api_routes,node_auth,node_user,node_policy,node_client toneBlue
class node_url_api,node_url_requests,node_url_service,node_code_generator,node_url_model,node_url_resource,node_redirect_route,node_redirect,node_prune toneAmber
class node_click_job,node_analytics_service,node_click_model,node_stats toneMint
class node_security,node_rate_limits,node_api_docs toneRose
class node_visitor toneIndigo
```

## Components

### API and access

- [API routes](https://github.com/allaingaye/url-shortener/blob/main/routes/api.php): `routes/api.php`
- [Account and tokens](https://github.com/allaingaye/url-shortener/blob/main/app/Http/Controllers/Api/AuthController.php): `app/Http/Controllers/Api/AuthController.php`
- [User accounts](https://github.com/allaingaye/url-shortener/blob/main/app/Models/User.php): `app/Models/User.php`
- [URL ownership policy](https://github.com/allaingaye/url-shortener/blob/main/app/Policies/UrlPolicy.php): `app/Policies/UrlPolicy.php`

### Link lifecycle

- [URL management](https://github.com/allaingaye/url-shortener/blob/main/app/Http/Controllers/Api/UrlController.php): `app/Http/Controllers/Api/UrlController.php`
- [URL validation](https://github.com/allaingaye/url-shortener/tree/main/app/Http/Requests): `app/Http/Requests`
- [URL service](https://github.com/allaingaye/url-shortener/blob/main/app/Services/UrlService.php): `app/Services/UrlService.php`
- [Code generator](https://github.com/allaingaye/url-shortener/blob/main/app/Services/ShortCodeGenerator.php): `app/Services/ShortCodeGenerator.php`
- [URL records](https://github.com/allaingaye/url-shortener/blob/main/app/Models/Url.php): `app/Models/Url.php`
- [URL response](https://github.com/allaingaye/url-shortener/blob/main/app/Http/Resources/UrlResource.php): `app/Http/Resources/UrlResource.php`
- [Redirect route](https://github.com/allaingaye/url-shortener/blob/main/routes/web.php): `routes/web.php`
- [Redirect handler](https://github.com/allaingaye/url-shortener/blob/main/app/Http/Controllers/RedirectController.php): `app/Http/Controllers/RedirectController.php`
- [Expired URL pruning](https://github.com/allaingaye/url-shortener/blob/main/app/Console/Commands/PruneExpiredUrls.php): `app/Console/Commands/PruneExpiredUrls.php`

### Click analytics

- [Click job](https://github.com/allaingaye/url-shortener/blob/main/app/Jobs/RecordClick.php): `app/Jobs/RecordClick.php`
- [Analytics capture](https://github.com/allaingaye/url-shortener/blob/main/app/Services/AnalyticsService.php): `app/Services/AnalyticsService.php`
- [Click records](https://github.com/allaingaye/url-shortener/blob/main/app/Models/Click.php): `app/Models/Click.php`
- [Analytics endpoint](https://github.com/allaingaye/url-shortener/blob/main/app/Http/Controllers/Api/UrlStatsController.php): `app/Http/Controllers/Api/UrlStatsController.php`

### Runtime safeguards

- [Security headers](https://github.com/allaingaye/url-shortener/blob/main/app/Http/Middleware/SecurityHeaders.php): `app/Http/Middleware/SecurityHeaders.php`
- [Rate limiting](https://github.com/allaingaye/url-shortener/blob/main/routes/api.php): `routes/api.php`
- [OpenAPI documentation](https://github.com/allaingaye/url-shortener/blob/main/app/OpenApi/OpenApi.php): `app/OpenApi/OpenApi.php`

### Other components

- **API client**
- **Link visitor**

## Connections

- API client → API routes: calls API
- API routes → Account and tokens: routes auth (evidence: `routes/api.php`)
- Account and tokens → User accounts: creates and authenticates (evidence: `app/Http/Controllers/Api/AuthController.php`)
- API routes → URL management: routes URL operations (evidence: `routes/api.php`)
- URL management → URL validation: validates input (evidence: `app/Http/Controllers/Api/UrlController.php`)
- URL management → URL service: delegates URL actions (evidence: `app/Http/Controllers/Api/UrlController.php`)
- URL service → Code generator: generates codes (evidence: `app/Services/UrlService.php`)
- URL service → URL records: creates and resolves (evidence: `app/Services/UrlService.php`)
- URL management → URL response: formats responses (evidence: `app/Http/Controllers/Api/UrlController.php`)
- URL management → URL ownership policy: authorizes ownership
- Link visitor → Redirect route: requests short link
- Redirect route → Redirect handler: dispatches redirect (evidence: `routes/web.php`)
- Redirect handler → URL service: resolves code (evidence: `app/Http/Controllers/RedirectController.php`)
- Redirect handler → URL records: increments clicks (evidence: `app/Http/Controllers/RedirectController.php`)
- Redirect handler → Click job: dispatches click (evidence: `app/Http/Controllers/RedirectController.php`)
- Click job → Analytics capture: records event (evidence: `app/Jobs/RecordClick.php`)
- Analytics capture → Click records: persists click details (evidence: `app/Services/AnalyticsService.php`)
- API routes → Analytics endpoint: routes statistics (evidence: `routes/api.php`)
- Analytics endpoint → Click records: aggregates click data (evidence: `app/Http/Controllers/Api/UrlStatsController.php`)
- Analytics endpoint → URL ownership policy: checks URL ownership
- Expired URL pruning → URL records: prunes expired URLs (evidence: `app/Console/Commands/PruneExpiredUrls.php`)
- Security headers → API routes: protects requests
- Rate limiting → API routes: limits requests (evidence: `routes/api.php`)
- OpenAPI documentation → API client: documents API
