Init

README.md

@@ -0,0 +1,124 @@
+# Core Module
+
+A Laravel module providing authentication, notifications, activity logging, CLI tooling, and functional types on top of the [Lunar](https://lunarphp.io) admin panel. Designed to be consumed as a standalone Composer package.
+
+---
+
+## What's Inside
+
+### OTP Authentication
+
+Passwordless login for both staff (Lunar panel) and customers via 6-digit codes delivered by email. Codes expire after 10 minutes. The Lunar panel login page is a two-step flow: email → OTP. Rate-limited to 5 attempts.
+
+See [`docs/otp-auth.md`](docs/otp-auth.md).
+
+### Notification Registry
+
+An event-driven notification system. Each notification class declares which event it listens to and who to notify — the registry wires up the listener automatically. All notifications extend `BaseNotification` which implements `ShouldQueue`, so delivery is async. Supports optional delays.
+
+**Creating a notification:**
+
+```php
+class MyNotification extends BaseNotification
+{
+    public function __construct(private readonly MyEvent $event) {}
+
+    public static function getKey(): string { return 'my.notification.key'; }
+    public static function listensTo(): string { return MyEvent::class; }
+    public function via(object $notifiable): array { return ['mail']; }
+    public function notifiable(): AnonymousNotifiable { ... }
+}
+
+// Register in a service provider:
+NotificationRegistry::get()->register([MyNotification::class]);
+```
+
+### Activity Logging
+
+Thin wrapper around [Spatie Laravel Activity Log](https://github.com/spatie/laravel-activitylog). Four standardized methods: `created()`, `updated()`, `failed()`, `deleted()`. Logs to the `lunar` channel and auto-resolves the actor from the staff session.
+
+See [`docs/activity-log.md`](docs/activity-log.md).
+
+### Lunar Panel Integration
+
+- Custom OTP login page replacing the default Lunar panel login
+- `StaffResourceExtension` — removes password field from Lunar's staff resource
+- `CustomerResourceExtension` — replaces default address relation manager with a custom implementation
+- `CorePlugin` — configures panel path, branding, logos, navigation items, and activity log field exclusions for staff
+
+Register the plugin in your Lunar panel provider:
+
+```php
+->plugin(\Modules\Core\CorePlugin::make())
+```
+
+### CLI Commands
+
+| Command | Description |
+|---|---|
+| `core:create-admin` | Create a Lunar admin user |
+| `core:anonymize` | GDPR anonymization of users and customers (local only) |
+| `core:export` | Dump database + storage files to a timestamped zip |
+| `core:import` | Restore from a zip export (runs anonymize automatically, local only) |
+| `core:export-cleanup` | Delete old export zips, keep N most recent |
+
+### Functional Types
+
+Result and Option monads for explicit error handling without exceptions.
+
+```php
+// Result<T, E>
+$result = Success::of($value);
+$result = Error::of('something went wrong');
+$result->map(fn($v) => ...)->flatMap(fn($v) => ...);
+
+// Option<T>
+$option = Option::fromValue($nullableValue);
+$option->getOrElse('default');
+$option->map(fn($v) => ...)->filter(fn($v) => $v > 0);
+```
+
+---
+
+## Installation
+
+Add the repository to your project's `composer.json`:
+
+```json
+{
+    "repositories": [
+        {
+            "type": "vcs",
+            "url": "https://code.radical-elements.com/boboko/core.git"
+        }
+    ],
+    "require": {
+        "boboko/core": "^1.0"
+    }
+}
+```
+
+Then run:
+
+```bash
+composer require radical-elements/core
+php artisan vendor:publish --tag=core-assets
+php artisan migrate
+```
+
+---
+
+## Requirements
+
+- PHP 8.2+
+- Laravel 11+
+- Lunar (lunarphp/lunar + lunarphp/admin)
+- Spatie Laravel Activity Log
+
+---
+
+## Documentation
+
+- [`docs/otp-auth.md`](docs/otp-auth.md) — OTP authentication flow
+- [`docs/activity-log.md`](docs/activity-log.md) — Activity logging
+- [`docs/lunar.md`](docs/lunar.md) — Lunar framework reference