# Architecture Notes

Onisokien Links is a standard monolithic Laravel application.

## Core Services

- **SlugGenerator**: Generates collision-free 5-character shortcodes using a clean dictionary of non-confusing characters.
- **DeviceClassifier**: Parses the `User-Agent` header to categorize traffic into iOS, Android, Web, or Bot. Bots are strictly segregated to avoid muddying marketing metrics.
- **DestinationResolver**: Determines the final redirect target based on the Link type (Short vs. Smart) and device classification.
- **MarketingParameterMerger**: Whitelists specific tracking parameters (like `utm_source`, `gclid`) and appends them to the destination URL while sanitizing inputs.
- **ClickRecorder**: Asynchronously-safe analytics recorder that logs clicks and atomically increments counters. Wrapped in a try/catch to fail-open (redirect proceeds even if analytics fail).

## Database Schema

We use a unified `links` table for both Short and Smart links to simplify unique slug constraints and unified querying.

- `links`: Contains metadata, start/expiry dates, destinations, and aggregate counters.
- `clicks`: Append-only log of every interaction. Indexed by link, date, platform, and bot status.
- `link_audits`: Tracks all mutations (create/update/archive) for accountability.

## Performance Considerations

- **Caching**: Dashboard metrics are cached for 5 minutes to prevent heavy aggregations on every page load.
- **Indexing**: Slug lookups are indexed. Time-series analytics queries are supported by composite indexes on `link_id` + `clicked_at`.
- **Stateless Redirects**: Public redirects do not hit the session store, avoiding lock contention and saving DB resources.

## Privacy

- Raw IP addresses are **never** stored. They are hashed immediately via HMAC-SHA-256 with a secret salt (`ANALYTICS_HASH_KEY`), yielding an anonymous unique identifier for basic frequency capping/fraud detection.
- A scheduled artisan command `app:prune-clicks` deletes granular click data older than `ANALYTICS_RETENTION_DAYS`, ensuring compliance with minimal data retention policies while maintaining lifetime aggregated link counters.