# Company SSO — Admin Panel

A single sign-on (SSO) administration panel built with **Laravel 13**, **Livewire 4**, and **Flux UI 2**. It provides user management, authentication flows (including two-factor authentication), profile & security settings, and a dashboard — all rendered server-side with reactive Livewire components.

---

## Table of Contents

- [Tech Stack](#tech-stack)
- [Requirements](#requirements)
- [Installation](#installation)
- [Running the Application](#running-the-application)
- [Available Commands](#available-commands)
- [Project Structure](#project-structure)
- [Authentication Features](#authentication-features)
- [Testing](#testing)
- [Code Style](#code-style)
- [Libraries & Documentation](#libraries--documentation)
- [License](#license)

---

## Tech Stack

| Layer      | Technology                  | Version |
| ---------- | --------------------------- | ------- |
| Framework  | Laravel                     | 13.x    |
| PHP        | PHP                         | 8.3+    |
| Frontend   | Livewire                    | 4.x     |
| CSS        | Tailwind CSS                | 4.x     |
| Bundler    | Vite                        | 8.x     |
| Auth       | Laravel Fortify             | 1.x     |
| Icons      | Blade Lucide Icons          | 1.x     |
| DTOs       | Spatie Laravel Data         | 4.x     |
| Testing    | Pest                        | 4.x     |
| Linting    | Laravel Pint                | 1.x     |
| Database   | SQLite (default) / MySQL    | —       |

---

## Requirements

- **PHP** ≥ 8.3
- **Composer** ≥ 2.x
- **Node.js** ≥ 20.x & **npm** ≥ 10.x
- **SQLite** (default) or any Laravel-supported database

---

## Installation

### 1. Clone the repository

```bash
git clone <repository-url> sentientgeeks_admin_sso
cd sentientgeeks_admin_sso
```

### 2. Install PHP dependencies

```bash
composer install
```

### 3. Configure environment

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

Edit `.env` to configure your database, mail, and other services as needed. The default configuration uses **SQLite** — no extra setup required.

### 4. Create the database

For SQLite (default):

```bash
touch database/database.sqlite
```

For MySQL/PostgreSQL, update the `DB_*` variables in `.env` accordingly.

### 5. Run migrations

```bash
php artisan migrate
```

### 6. Install Node dependencies & build assets

```bash
npm install
npm run build
```

### Quick Setup (all-in-one)

Alternatively, run the bundled setup script that performs steps 2–6 automatically:

```bash
composer setup
```

---

## Running the Application

### Development (recommended)

Start **all** development services concurrently — web server, queue worker, log tail, and Vite dev server:

```bash
composer run dev
```

This launches:

| Service       | URL / Info                         |
| ------------- | ---------------------------------- |
| Laravel server | `http://localhost:8000`            |
| Queue worker  | Listens with `--tries=1`           |
| Pail (logs)   | Real-time log streaming            |
| Vite          | HMR & asset compilation            |

### Production build

```bash
npm run build
php artisan serve
```

---

## Available Commands

| Command               | Description                                              |
| --------------------- | -------------------------------------------------------- |
| `composer setup`      | Full project setup (install, env, migrate, build)        |
| `composer run dev`    | Start all dev services concurrently                      |
| `composer run lint`   | Fix code style with Pint                                 |
| `composer run lint:check` | Check code style without modifying files             |
| `composer run test`   | Clear config, lint-check, and run all tests              |
| `npm run dev`         | Start Vite dev server with HMR                           |
| `npm run build`       | Build production assets                                  |

---

## Livewire Commands
```bash
    # Create a new Livewire component, follow dot (.) notation for sub-folders in name
    php artisan make:livewire <name>
    
    # Create a page component (full-page Livewire component)
    php artisan make:livewire pages::<name> --page
```

## Project Structure

```
├── app/
│   ├── Actions/Fortify/       # Auth action classes (create user, reset password)
│   ├── Concerns/              # Shared traits (validation rules)
│   ├── Data/Ui/               # Spatie Data DTOs for UI (Connected Services)
│   ├── Enums/                 # ConnectionStatus, ConnectionTechTypes
│   ├── Http/Controllers/      # HTTP controllers
│   ├── Livewire/
│   │   ├── Actions/           # Livewire action classes (Logout)
│   │   └── Settings/          # Settings components (Profile, Security, Appearance, 2FA)
│   ├── Models/                # Eloquent models (User)
│   └── Providers/             # Service providers (App, Fortify)
├── config/                    # Application configuration
├── database/
│   ├── factories/             # Model factories
│   ├── migrations/            # Database migrations
│   └── seeders/               # Database seeders
├── resources/
│   ├── css/                   # Tailwind CSS entry point
│   ├── js/                    # JavaScript entry point
│   └── views/
│       ├── components/        # Blade components (sidebar, topbar, logos)
│       ├── flux/              # Flux UI component overrides
│       ├── layouts/           # Application layouts
│       ├── livewire/
│       │   ├── auth/          # Auth views (login, register, 2FA, etc.)
│       │   └── settings/      # Settings views (profile, security, appearance)
│       ├── pages/             # Full-page Livewire components (dashboard)
│       └── partials/          # Reusable view partials
├── routes/
│   ├── web.php                # Main web routes
│   ├── settings.php           # Settings routes (profile, security, appearance)
│   └── console.php            # Artisan console routes
├── tests/
│   ├── Feature/               # Feature tests (Auth, Settings, Dashboard)
│   └── Unit/                  # Unit tests
├── vite.config.js             # Vite + Tailwind CSS v4 + Laravel plugin config
├── composer.json
└── package.json
```

---

## Authentication Features

Powered by **Laravel Fortify**, the application supports:

- **Registration** — New user sign-up
- **Login / Logout** — Session-based authentication with rate limiting
- **Password Reset** — Forgot password & reset via email
- **Email Verification** — Verify email address flow
- **Two-Factor Authentication (2FA)** — TOTP-based with QR codes and recovery codes
- **Password Confirmation** — Re-confirm password before sensitive actions
- **Profile Management** — Update name, email
- **Account Deletion** — Self-service account removal

---

## Testing

This project uses **Pest** for testing.

```bash
# Run all tests
php artisan test --compact

# Run a specific test file
php artisan test --compact --filter=LoginTest

# Full CI check (lint + test)
composer run test
```

---

## Code Style

Code style is enforced with **Laravel Pint**. After modifying PHP files:

```bash
# Auto-fix formatting
vendor/bin/pint --parallel

# Check without modifying
vendor/bin/pint --test
```

---

## Libraries & Documentation

### Core Framework

| Library | Description | Docs |
| --- | --- | --- |
| **Laravel 13** | PHP web application framework | [laravel.com/docs](https://laravel.com/docs) |
| **PHP 8.3+** | Server-side language | [php.net/docs](https://www.php.net/docs.php) |

### Frontend & UI

| Library | Description | Docs |
| --- | --- | --- |
| **Livewire 4** | Full-stack reactive components for Laravel | [livewire.laravel.com/docs](https://livewire.laravel.com/docs) |
| **Tailwind CSS 4** | Utility-first CSS framework | [tailwindcss.com/docs](https://tailwindcss.com/docs) |
| **Alpine.js** | Lightweight JS framework (bundled with Livewire) | [alpinejs.dev](https://alpinejs.dev/) |
| **Blade Lucide Icons** | Lucide icon set for Blade templates | [github.com/mallardduck/blade-lucide-icons](https://github.com/mallardduck/blade-lucide-icons) |

### Authentication

| Library | Description | Docs |
| --- | --- | --- |
| **Laravel Fortify 1** | Backend authentication scaffolding | [laravel.com/docs/fortify](https://laravel.com/docs/fortify) |

### Data & Architecture

| Library | Description | Docs |
| --- | --- | --- |
| **Spatie Laravel Data 4** | Typed data transfer objects | [spatie.be/docs/laravel-data](https://spatie.be/docs/laravel-data) |
| **Tailwind Merge Laravel** | Intelligent Tailwind class merging in PHP | [github.com/gehrisandro/tailwind-merge-laravel](https://github.com/gehrisandro/tailwind-merge-laravel) |

### Build Tools

| Library | Description | Docs |
| --- | --- | --- |
| **Vite 8** | Next-generation frontend build tool | [vite.dev/guide](https://vite.dev/guide/) |
| **Laravel Vite Plugin 3** | Laravel integration for Vite | [laravel.com/docs/vite](https://laravel.com/docs/vite) |

### Development & Testing

| Library | Description | Docs |
| --- | --- | --- |
| **Pest 4** | Elegant PHP testing framework | [pestphp.com/docs](https://pestphp.com/docs) |
| **Laravel Pint 1** | Opinionated PHP code style fixer | [laravel.com/docs/pint](https://laravel.com/docs/pint) |
| **Laravel Sail 1** | Docker development environment | [laravel.com/docs/sail](https://laravel.com/docs/sail) |
| **Laravel Pail 1** | Real-time log viewer | [laravel.com/docs/pail](https://laravel.com/docs/pail) |
| **Laravel Tinker 3** | REPL for Laravel | [laravel.com/docs/artisan#tinker](https://laravel.com/docs/artisan#tinker) |
| **FakerPHP** | Fake data generator for testing | [fakerphp.org](https://fakerphp.org/) |
| **Mockery** | Mock object framework for PHP | [docs.mockery.io](https://docs.mockery.io/) |

---

## License

This project is proprietary software. All rights reserved.