phase 5

PLAN.md

@@ -2,6 +2,20 @@
 
 A self-hosted error tracking application (inspired by [Bugsink](https://www.bugsink.com/) / Sentry) built on this Laravel 13 app.
 
+## Overview
+
+This is an **error tracking application similar to Sentry**, designed to receive and aggregate errors from applications running in production. Users integrate SDKs into their applications (PHP, JavaScript, Python, etc.), and those SDKs send error events **directly** to our tracking server in real-time when errors occur.
+
+### How It Works
+
+1. **SDK Integration**: Developers install a Sentry-compatible SDK in their application (e.g., `sentry/sentry-laravel` for Laravel, `@sentry/browser` for JavaScript, `sentry-python` for Python).
+2. **Configuration**: They configure the SDK with a DSN (Data Source Name) pointing to our tracking server.
+3. **Automatic Error Capture**: When an error occurs in their application, the SDK automatically captures the error context (stacktrace, breadcrumbs, user info, request details) and sends it to our server.
+4. **Real-Time Processing**: Our server receives the error payload, groups similar errors into issues, and displays them in a web dashboard.
+5. **Notifications**: Teams are notified when new issues occur or when resolved issues regress.
+
+This architecture means we don't need to build custom SDKs — we leverage the entire ecosystem of existing Sentry SDKs by implementing a Sentry-compatible ingestion API.
+
 ## Stack Summary
 
 | Layer | Technology |
@@ -12,6 +26,52 @@ A self-hosted error tracking application (inspired by [Bugsink](https://www.bugs
 | Queue | Database driver (upgrade to Redis for production) |
 | Auth | Laravel Breeze (installed) |
 
+## SDK Support & Multi-Language Integration
+
+### Supported Languages & Frameworks
+
+Our tracking server accepts error events from **any Sentry-compatible SDK**, enabling broad language and framework support without custom development:
+
+| Language/Platform | Official Sentry SDK | Notes |
+|-------------------|---------------------|-------|
+| **PHP** | `sentry/sentry-laravel`, `sentry/sentry-symfony`, `sentry/sentry` | Full Laravel, Symfony, and native PHP support |
+| **JavaScript/Node.js** | `@sentry/browser`, `@sentry/node`, `@sentry/react`, `@sentry/vue`, `@sentry/angular` | Frontend and backend JS, plus framework-specific integrations |
+| **Python** | `sentry-sdk` | Django, Flask, FastAPI, etc. |
+| **Ruby** | `sentry-ruby`, `sentry-rails` | Rails and native Ruby support |
+| **Java** | `io.sentry:sentry` | Spring, Android, and JVM languages |
+| **Go** | `github.com/getsentry/sentry-go` | Native Go support |
+| **.NET/C#** | `Sentry.AspNetCore`, `Sentry` | ASP.NET Core, .NET Framework |
+| **Mobile** | `@sentry/react-native`, `sentry-android`, `sentry-cocoa` | React Native, Android (Java/Kotlin), iOS (Swift/Obj-C) |
+| **Rust** | `sentry` | Native Rust support |
+| **Elixir** | `sentry` | Phoenix and Elixir support |
+
+### SDK Configuration Example
+
+Users simply point the official Sentry SDK to our server:
+
+**PHP (Laravel):**
+```php
+// config/sentry.php
+'dsn' => 'https://<public_key>@trackbugs.example.com/api/<project_id>/store/',
+```
+
+**JavaScript:**
+```javascript
+Sentry.init({
+  dsn: 'https://<public_key>@trackbugs.example.com/api/<project_id>/store/',
+});
+```
+
+**Python:**
+```python
+import sentry_sdk
+sentry_sdk.init(
+    dsn="https://<public_key>@trackbugs.example.com/api/<project_id>/store/"
+)
+```
+
+No custom SDK development is required — our server implements the Sentry protocol, so all existing SDKs work out of the box.
+
 ---
 
 ## Phase 1 — Foundation & Auth
@@ -206,19 +266,19 @@ Clients configure this DSN in their Sentry SDK — no changes needed on the SDK
 
 ### 5.1 Release Tracking
 
-- [ ] Parse `release` field from events
-- [ ] Show which release introduced an issue
-- [ ] Mark issues as resolved-in-release; auto-regress if they appear in a newer release
+- [x] Parse `release` field from events
+- [x] Show which release introduced an issue
+- [x] Mark issues as resolved-in-release; auto-regress if they appear in a newer release
 
 ### 5.2 Environment Filtering
 
-- [ ] Global environment selector (production / staging / etc.)
-- [ ] Filter issues and events by environment
+- [x] Global environment selector (production / staging / etc.)
+- [x] Filter issues and events by environment
 
 ### 5.3 Retention & Cleanup
 
-- [ ] Artisan command / scheduled job to delete events older than N days (configurable)
-- [ ] Keep issue summaries even after events are pruned
+- [x] Artisan command / scheduled job to delete events older than N days (configurable)
+- [x] Keep issue summaries even after events are pruned
 
 ### 5.4 Source Maps / Source Context (optional, stretch)
 
@@ -227,8 +287,8 @@ Clients configure this DSN in their Sentry SDK — no changes needed on the SDK
 
 ### 5.5 API Tokens & External API
 
-- [ ] Personal API tokens for programmatic access
-- [ ] REST API for listing/resolving issues (useful for CI/CD integrations)
+- [x] Personal API tokens for programmatic access
+- [x] REST API for listing/resolving issues (useful for CI/CD integrations)
 
 ---
 
@@ -258,14 +318,14 @@ Clients configure this DSN in their Sentry SDK — no changes needed on the SDK
 
 ### Milestone 4 — Production-readiness
 - [ ] 17. Rate limiting on ingest
-- [ ] 18. Event retention / cleanup scheduler
-- [ ] 19. Release tracking
-- [ ] 20. Environment filtering
+- [x] 18. Event retention / cleanup scheduler
+- [x] 19. Release tracking
+- [x] 20. Environment filtering
 - [ ] 21. Performance optimization (indexes, query tuning, caching)
 
 ### Milestone 5 — Advanced (stretch)
 - [ ] 22. Source map upload & processing
-- [ ] 23. API tokens & external REST API
+- [x] 23. API tokens & external REST API
 - [ ] 24. Webhook / Slack notifications
 - [ ] 25. CQRS-style read models for heavy dashboards (if needed)