# Roxane

Roxane is an open source membership management application designed for associations. It centralizes member management, subscriptions, and integration with self-hosted third-party services (Dolibarr, ISPConfig, Nextcloud, Sympa).

The project is developed in the context of **Le Retzien Libre**, a non-profit association promoting digital freedom and self-hosting. It is intended to be generic enough to be adapted by other associations with similar needs.

> Work in progress. The application is functional for core features but is actively being developed. See the [known TODOs](#known-todos) section.

---

## Features

**Back office (administrators)**
- Member management (status, nature, groups)
- Subscription and package management with validation workflow (pending → active)
- Manual and automated synchronization with third-party services
- Role and permission management (Spatie Permissions + Filament Shield)
- Two-factor authentication for admin accounts

**Front office (members)**
- Registration and membership form with real-time field validation
- Personal dashboard with access to associated services
- Profile and password management
- Two-factor authentication

**Email notifications**
- Admin notified on new contact request and new membership request (with direct link to the membership record)
- Member receives a confirmation email on registration and a validation email when approved
- Member notified on account deactivation and subscription expiry
- Queued notifications (`ShouldQueue`) — requires a running queue worker
- Separate application name for member emails (`FRONT_NAME`) vs admin emails (`APP_NAME`)

**Integrations**
- Dolibarr ERP (member and subscription import via REST API)
- ISPConfig (mail and web hosting account management via SOAP)
- Nextcloud (account provisioning via OCS API)
- Sympa (mailing list management)

**Planned in V2**
- SSO authentication via Keycloak (OIDC) for the front office
- Admin back office remains on local Laravel authentication

---

## Tech stack

| Layer     | Technologies                                          |
|-----------|-------------------------------------------------------|
| Backend   | Laravel 12, PHP 8.3, MySQL                            |
| Admin     | Filament v4, Livewire 3                               |
| Frontend  | React 19, Inertia v2, Tailwind CSS v4                 |
| Auth      | Laravel Fortify, 2FA, Spatie Permissions + Shield     |
| Queue     | Redis (cache, sessions, queues)                       |
| Tests     | PHPUnit 11                                            |
| Dev tools | Pint, ESLint, Prettier, Laravel Sail, Wayfinder       |

---

## Requirements

- PHP 8.3+
- Composer
- Node.js 20+ and npm
- MySQL 8+ or MariaDB 10.6+
- Redis
- Docker (optional, via Laravel Sail)

---

## Installation

### 1. Clone the repository

```bash
git clone https://github.com/SabrinaNebulae/roxane.git
cd roxane
```

### 2. Install dependencies

```bash
composer install
npm install
```

### 3. Environment configuration

```bash
cp .env.example .env
php artisan key:generate
```

Edit `.env` and configure:
- Database connection (`DB_*`)
- Redis connection (`REDIS_*`)
- Mail configuration (`MAIL_*`)
- Application names: `APP_NAME` (admin panel), `FRONT_NAME` (member-facing emails)
- Admin email: `ADMIN_EMAIL` (recipient for all admin notifications)
- Third-party service credentials (Dolibarr, ISPConfig, Nextcloud)

### 4. Database setup

```bash
php artisan migrate
php artisan db:seed
```

The seeder creates:
- Member groups (`admin-interface`, `website`)
- Default packages (`custom`, `one-year`, `two-years`)
- Default services (mail, file2link, nextcloud, sympa, webhosting)
- Admin account (`contact@nebulae-design.com` / `password`)
- Notification templates

In non-production environments, a demo member (Jane Doe) is also created.

**Change all default credentials immediately after installation.**

### 5. Build frontend assets

```bash
npm run build
```

For local development with hot reload:

```bash
npm run dev
```

Or use the all-in-one development command:

```bash
composer run dev
```

### 6. Queues and scheduler

The application uses queued jobs for synchronization tasks and notifications. In production, configure a queue worker and the Laravel scheduler.

```bash
# Queue worker
php artisan queue:work

# Scheduler (add to crontab)
* * * * * cd /path/to/roxane && php artisan schedule:run >> /dev/null 2>&1
```

---

## Running with Laravel Sail (Docker)

```bash
./vendor/bin/sail up -d
./vendor/bin/sail artisan migrate
./vendor/bin/sail artisan db:seed
./vendor/bin/sail npm run build
```

---

## Default accounts

| Account     | Email                       | Password | Role        |
|-------------|----------------------------|----------|-------------|
| Admin       | contact@nebulae-design.com | password | super_admin |
| Demo member | jane@doe.com               | password | —           |

These accounts are created by the seeder. Remove or change them before any production deployment.

---

## Artisan commands

Synchronization commands can be triggered manually from the admin panel (Synchronisations page) or via CLI:

| Command                        | Description                                                  |
|-------------------------------|--------------------------------------------------------------|
| `sync:dolibarr-members`       | Import members and subscriptions from Dolibarr               |
| `members:cleanup-expired`     | Deactivate expired members across all services (`--dry-run`) |
| `sync:ispconfig-mail-members` | Link members to their ISPConfig mail accounts                |
| `sync:ispconfig-web-members`  | Link members to their ISPConfig web hosting accounts         |
| `nextcloud:sync-members`      | Link members to their Nextcloud accounts                     |
| `memberships:sync-services`   | Synchronize services associated with active memberships      |

---

## Running tests

```bash
php artisan test --compact
```

---

## Known TODOs

| Area                        | Description                                                                      |
|-----------------------------|----------------------------------------------------------------------------------|
| Notifications               | Propagate `appName` view variable to all remaining notifications                 |
| SubscriptionExpiredPhase1   | Backend UI for editing notification template content                             |
| MembershipValidatedNotif.   | Add HelloAsso payment link once integration is available                         |
| User.php                    | Restrict admin access in production to @retzien.fr emails                        |
| SyncDolibarrMembers         | Extract `toDate()` method into a shared service or helper                        |
| SyncISPConfigMailMembers    | Handle multiple email addresses per member                                       |
| SyncISPConfigMailMembers    | Track `ispconfig_client_id`                                                      |
| Global                      | Make Roxane fully generic for any association ERP use case                       |
| Translations                | Audit project for missing translation keys                                       |
| Global                      | Raise PHPStan to level 8                                                         |
| dev-routes.php              | Remove `/test/mail` debug route before production deployment                     |
| V2                          | Keycloak SSO integration (OIDC) for front office authentication                  |

---

## License

This project is licensed under the [GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0).

Any modification to the source code, including versions run as a network service, must be made available under the same license. This ensures the project remains free and open for all.

Contributions are welcome. If you are adapting Roxane for your own association, feel free to open an issue or submit a pull request.