105123bb74
- Added Role and User DTOs for dynamic role handling. - Implemented table and badge components for displaying role data. - Registered a Blade directive for scoped slots in `ScopeServiceProvider`. - Updated dashboard views to include role management section.
304 lines
10 KiB
Markdown
304 lines
10 KiB
Markdown
# 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.
|