# BASIS

This project, **BASIS**, is a modular, multi-tenant enterprise platform built with PHP. It implements a robust PSR-7/PSR-15 compliant architecture with advanced security features and modern frontend integration via Hotwire Turbo. 

Based on the provided UML sequence diagram and codebase, here is a structured introduction to the project:

## 1. HTTP Request Pipeline & Middleware Stack
The application uses a layered middleware pipeline to process requests securely before they reach the business logic:
*   **Entry Point & Kernel**: Requests enter via `public/index.php` and are dispatched by the `Http\Kernel` (`core/Http/Kernel.php`).
*   **Tenant Resolution**: `TenantResolutionMiddleware` (`src/Http/Middleware/TenantResolutionMiddleware.php`) resolves the current tenant from the request host and switches the database connection context accordingly.
*   **RLS Session Context**: `DbSessionMiddleware` (`core/Http/Middleware/DbSessionMiddleware.php`) sets PostgreSQL session variables (like `app.current_user_id`) to enforce Row-Level Security (RLS) policies at the database level.
*   **Security Middlewares**: `CsrfMiddleware` validates CSRF tokens, and `RateLimiterMiddleware` prevents brute-force attacks.
*   **Turbo Detection**: `TurboStreamDetector` (`core/Http/TurboStreamDetector.php`) identifies if the request originates from Hotwire Turbo, allowing the controller to return `TurboStreamResponse` instead of full HTML.

## 2. Advanced Authentication & Security Flow
The platform implements a sophisticated, multi-layered authentication system:
*   **Core Authentication**: `AuthService` (`core/Auth/AuthService.php`) handles credential verification and session creation via `SessionManager`.
*   **Multi-Factor Authentication (MFA)**: If enabled, `MfaService` (`core/Auth/MfaService.php`) enforces a TOTP challenge. Users can verify via authenticator apps or backup codes.
*   **WebAuthn/Biometrics**: As an alternative MFA factor, `WebAuthnService` (`core/Auth/WebAuthn/WebAuthnService.php`) handles biometric authentication (FaceID, fingerprint) and hardware security keys.
*   **User Context**: Upon successful login, `UserProfileAgent` (`core/Agents/UserProfileAgent.php`) initializes the user's profile, permissions, and runtime context.

## 3. Modern Frontend Integration (Hotwire Turbo)
Instead of building a heavy SPA, the project uses **Hotwire Turbo** for a fast, modern UX:
*   The `TurboStreamDetector` intercepts responses from the `App Controller`.
*   If the client expects a Turbo Stream, the system formats a `TurboStreamResponse` (`core/Http/Response/TurboStreamResponse.php`), sending only the modified DOM fragments to the browser.
*   This allows seamless, SPA-like navigation without writing custom JavaScript, while keeping the server as the source of truth.

## 4. Modular & Multi-Tenant Architecture
The project is structured as a monorepo containing distinct "apps" and "modules":
*   **Multi-App Support**: It hosts multiple business applications like **Operand** (ERP), **Nexus** (BI/Strategy), **Axis** (Field Operations), and **Vector** (Engineering). Each app has its own controllers, views, and routing (`apps/operand`, `apps/nexus`, etc.).
*   **Core Modules**: Shared functionalities are abstracted into modules like `core-auth` (Authentication), `core-admin` (Administration), `audit`, and `files` (`modules/`).
*   **Database Isolation**: The `db_auth` schema centralizes user identities, while `TenantResolutionMiddleware` ensures data isolation per company using database-level RLS.

# BASIS Core Overview

BASIS Core is a modular framework and identity kernel for the BASIS ecosystem (which includes applications like Operand, Nexus, Vector, Codex, and Axis). It serves as a central authentication and modular platform for enterprise applications.

# Key Modules and Their Functions

## 1. Core Modules (in `/core/` directory)
- **Agents**: Likely handles agent-based operations or services
- **Auth**: Central authentication system implementing JWT, refresh token rotation, and session management
- **DB**: Database-related utilities and connection management
- **Http**: HTTP request handling, middleware, and routing
- **Mail**: Email handling functionality
- **MasterData**: Master data management utilities
- **Modules**: Core module management system
- **Support**: Support utilities and helper functions
- **View**: View rendering and templating system

## 2. Application Modules (in `/modules/` directory)
- **audit (sys-audit)**: Centralized audit logging and tracking system
- **catalog-master**: Master catalog management
- **configuration (sys-config)**: System-wide parameter management
- **core-admin**: Administrative panel for users, roles, and sessions
- **core-auth**: Core authentication functionality
- **core-dashboard**: User dashboard functionality
- **entity-master**: Entity management system
- **event-bus**: Event handling and messaging system
- **files (sys-files)**: File management using Flysystem
- **localization (sys-localization)**: Internationalization and translation support
- **notifications (sys-notifications)**: Multi-channel notification system
- **procurement-core**: Procurement-specific functionality
- **project-master**: Project management system
- **reporting (biz-reporting)**: Report generation and export
- **scheduler (sys-scheduler)**: Scheduled task/job management

## 3. Vertical Applications (in `/apps/` directory)
- **axis**: Specific application (possibly for analytics or BI)
- **codex**: Documentation or knowledge management application
- **nexus**: Central hub or integration application
- **operand**: ERP (Enterprise Resource Planning) application
- **synapse**: Connection or integration hub application
- **vector**: Data or application vector system

## 4. Shared Components (in `/shared/` directory)
- **components**: Reusable UI components
- **layouts**: Common layout templates
- **widgets**: UI widgets and modules

# **Code Organization**

## 1. Directory Structure
The project follows a clear hierarchical structure:
- **Root Level**: Configuration files, documentation, and deployment scripts
- **core/**: Core framework functionality
- **modules/**: Horizontal services and shared functionality
- **apps/**: Vertical applications built on the framework
- **shared/**: Shared UI components and utilities
- **config/**: Global configuration settings
- **docs/**: Comprehensive documentation
- **tests/**: Unit, integration, and end-to-end tests

## 2. Configuration System
- Central configuration in `/config/` with files for:
  - Application settings (`app.php`)
  - Authentication (`auth.php`)
  - Database connections (`database.php`)
  - Module management (`modules.php`, `enabled_modules.php`)
  - UI configuration (`theme.php`, `ui.php`)

## 3. Module System
- Each module has a `manifest.json` defining metadata, dependencies, permissions, and assets
- Modules can be enabled/disabled through configuration
- Modular architecture allows for selective feature implementation

## 4. Authentication System
- JWT-based authentication with refresh token rotation
- OIDC (OpenID Connect) support endpoints
- Multi-factor authentication (MFA) capabilities
- Role-based access control (RBAC) with attribute-based access control (ABAC) elements

## 5. Security Features
- CSRF protection
- Session management
- Row-level security (RLS) in database
- Modular branding theming system

## 6. API Design
- RESTful API with versioned endpoints (`/api/core/v1`)
- Clear separation between public and private endpoints
- Contract-based API design defined in `CORE_CONTRACT.md`

## 7. Frontend Components
- Uses Tailwind CSS for styling
- Modular UI components with semantic color aliases
- Turbo integration for enhanced user experience

# Technology Stack
- **PHP 8.1+** as the main programming language
- **PostgreSQL** for database management
- **Redis** for sessions, caching, and rate limiting
- **PSR standards** for HTTP handling and autoloading
- **Alpine.js/Turbo** for frontend interactivity
- **Flysystem** for file management
- **WebAuthn** for passwordless authentication

# Integration Points
- Event-driven architecture with hooks for user provisioning, updates, and tenant creation
- Modular menu system that can be extended by modules
- Multi-tenant architecture with tenant-specific data isolation

# Notable Features
1. **Modular Branding**: CSS variables and semantic aliases for consistent theming
2. **Dynamic Menu System**: Menu injection through manifests
3. **Multi-tenant Support**: Tenant mapping and isolation
4. **Audit Trail**: Comprehensive logging across modules
5. **Internationalization**: Built-in support for multiple languages

This architecture BASIS Core as a robust, extensible platform for building enterprise applications with strong authentication, modular design, and comprehensive security features.