Implement-account-entity

specs/accounts.md

@@ -1,39 +1,45 @@
 # Team & Account Management
 
 ## Overview
+
 StartupAPI uses a multi-tenant architecture where users belong to "Accounts". An Account acts as a container for data, subscriptions, and team members, effectively allowing a single user to participate in multiple organizations or workspaces.
 
 ## Key Components
 
 ### 1. Account Entity
-*   **Class**: `Account` (`classes/Account.php`)
-*   **Role**: The primary unit of tenancy and billing.
-*   **Attributes**:
-    *   `id`: Unique identifier.
-    *   `name`: Account name.
-    *   `plan`: Current subscription plan.
-    *   `active`: Status flag.
+
+- **Class**: `Account` (`classes/Account.php`)
+- **Role**: The primary unit of tenancy and billing.
+- **Attributes**:
+  - `id`: Unique identifier.
+  - `name`: Account name.
+  - `plan`: Current subscription plan.
+  - `active`: Status flag.
 
 ### 2. User-Account Relationship
-*   **Many-to-Many**: A user can belong to multiple accounts; an account can have multiple users.
-*   **Roles**:
-    *   `Account::ROLE_USER` (0): Standard member.
-    *   `Account::ROLE_ADMIN` (1): Account administrator (can manage billing and users).
-*   **Context**: Users switch between accounts. `User::getCurrentAccount()` retrieves the active context.
+
+- **Many-to-Many**: A user can belong to multiple accounts; an account can have multiple users.
+- **Roles**:
+  - `Account::ROLE_USER` (0): Standard member.
+  - `Account::ROLE_ADMIN` (1): Account administrator (can manage billing and users).
+- **Context**: Users switch between accounts. `User::getCurrentAccount()` retrieves the active context.
 
 ### 3. Invitations
-*   **Class**: `Invitation` (`classes/Invitation.php`)
-*   **Functionality**: Allows adding users to the system or specific accounts.
-*   **Flows**:
-    *   **Admin Invite**: System admins invite users to the platform.
-    *   **Account Invite**: Account admins invite members to their team.
-*   **Data**: Stores `code`, `issuer`, `recipient_email`, `target_account_id`.
+
+- **Class**: `Invitation` (`classes/Invitation.php`)
+- **Functionality**: Allows adding users to the system or specific accounts.
+- **Flows**:
+  - **Admin Invite**: System admins invite users to the platform.
+  - **Account Invite**: Account admins invite members to their team.
+- **Data**: Stores `code`, `issuer`, `recipient_email`, `target_account_id`.
 
 ## Workflows
-*   **Creation**: Every new user gets a personal Account by default.
-*   **Switching**: Users can switch context via the UI (usually top navigation).
-*   **Membership**: Account admins can add/remove users via the Account Settings page.
+
+- **Creation**: Every new user gets a personal Account by default.
+- **Switching**: Users can switch context via the UI (usually top navigation).
+- **Membership**: Account admins can add/remove users via the Account Settings page.
 
 ## Security
-*   **Isolation**: Data queries should be scoped to the `current_account` to ensure tenant isolation.
-*   **Permissions**: Only Account Admins can modify billing settings or plan subscriptions.
+
+- **Isolation**: Data queries should be scoped to the `current_account` to ensure tenant isolation.
+- **Permissions**: Only Account Admins can modify billing settings or plan subscriptions.

specs/admin.md

@@ -1,32 +1,38 @@
 # Administrative Control
 
 ## Overview
+
 The Admin Panel provides a centralized interface for platform owners to manage users, accounts, subscriptions, and system settings. It is secured to allow access only to users with global administrative privileges.
 
 ## Key Components
 
 ### 1. Admin Menu System
-*   **Class**: `MenuElement` (Abstract) and subclasses in `admin/adminMenus.php`.
-*   **Structure**: Hierarchical menu defining the admin navigation.
-*   **Features**:
-    *   Supports nested sub-menus.
-    *   Handles active state highlighting.
-    *   Can disable menu items with "Coming soon" tooltips.
+
+- **Class**: `MenuElement` (Abstract) and subclasses in `admin/adminMenus.php`.
+- **Structure**: Hierarchical menu defining the admin navigation.
+- **Features**:
+  - Supports nested sub-menus.
+  - Handles active state highlighting.
+  - Can disable menu items with "Coming soon" tooltips.
 
 ### 2. User & Account Administration
-*   **Users**: (`admin/users.php`) List, search, and edit user details.
-*   **Accounts**: (`admin/accounts.php`) Manage account statuses, view details, and intervene in billing issues.
-*   **Impersonation**: Admins can log in as any user to reproduce bugs or assist with configuration.
+
+- **Users**: (`admin/users.php`) List, search, and edit user details.
+- **Accounts**: (`admin/accounts.php`) Manage account statuses, view details, and intervene in billing issues.
+- **Impersonation**: Admins can log in as any user to reproduce bugs or assist with configuration.
 
 ### 3. Subscription Management
-*   **Plans**: (`admin/plans.php`) View and edit subscription plans.
-*   **Outstanding Payments**: (`admin/outstanding.php`) Monitor failed charges and overdue accounts.
-*   **Transaction Logs**: (`admin/transaction_log.php`) Audit trail of all financial transactions.
+
+- **Plans**: (`admin/plans.php`) View and edit subscription plans.
+- **Outstanding Payments**: (`admin/outstanding.php`) Monitor failed charges and overdue accounts.
+- **Transaction Logs**: (`admin/transaction_log.php`) Audit trail of all financial transactions.
 
 ### 4. System Settings & Modules
-*   **Settings**: (`admin/settings.php`) General platform configuration.
-*   **Modules**: (`admin/modules.php`) Enable/disable and configure system modules (Authentication, Payment, etc.).
+
+- **Settings**: (`admin/settings.php`) General platform configuration.
+- **Modules**: (`admin/modules.php`) Enable/disable and configure system modules (Authentication, Payment, etc.).
 
 ## Security
-*   **Access Control**: All admin pages verify that the current user has global admin privileges (`Account::ROLE_ADMIN` context on the system account or specific flag).
-*   **Audit**: Critical actions are logged.
+
+- **Access Control**: All admin pages verify that the current user has global admin privileges (`Account::ROLE_ADMIN` context on the system account or specific flag).
+- **Audit**: Critical actions are logged.

specs/api.md

@@ -1,34 +1,40 @@
 # Developer Platform / API
 
 ## Overview
+
 StartupAPI provides a RESTful API (v1) to allow external applications and client-side frontends to interact with the platform. It features a structured endpoint system, parameter validation, and authentication.
 
 ## Key Components
 
 ### 1. Endpoint Architecture
-*   **Base Class**: `Endpoint` (`classes/API/Endpoint.php`).
-*   **Registration**: Endpoints are registered to a namespace and HTTP method via `Endpoint::register()`.
-*   **Discovery**: `api.php` handles routing based on the URL structure (e.g., `/api/v1/user`).
+
+- **Base Class**: `Endpoint` (`classes/API/Endpoint.php`).
+- **Registration**: Endpoints are registered to a namespace and HTTP method via `Endpoint::register()`.
+- **Discovery**: `api.php` handles routing based on the URL structure (e.g., `/api/v1/user`).
 
 ### 2. Request Handling
-*   **Routing**: Logic in `Endpoint::getEndpoint()` resolves the URL slug to a specific handler.
-*   **Parameters**:
-    *   **Definition**: Endpoints define expected parameters (`Parameter` class).
-    *   **Validation**: Built-in type checking and required/optional validation.
-    *   **Parsing**: `parseURLEncoded` helper for processing input.
+
+- **Routing**: Logic in `Endpoint::getEndpoint()` resolves the URL slug to a specific handler.
+- **Parameters**:
+  - **Definition**: Endpoints define expected parameters (`Parameter` class).
+  - **Validation**: Built-in type checking and required/optional validation.
+  - **Parsing**: `parseURLEncoded` helper for processing input.
 
 ### 3. Authentication & Security
-*   **Base Class**: `AuthenticatedEndpoint`.
-*   **Mechanism**: automatically checks for a valid session or API token before processing the request.
-*   **Exceptions**:
-    *   `UnauthenticatedException` (401)
-    *   `UnauthorizedException` (403)
-    *   `MethodNotAllowedException`
+
+- **Base Class**: `AuthenticatedEndpoint`.
+- **Mechanism**: automatically checks for a valid session or API token before processing the request.
+- **Exceptions**:
+  - `UnauthenticatedException` (401)
+  - `UnauthorizedException` (403)
+  - `MethodNotAllowedException`
 
 ### 4. Core Endpoints
-*   **Namespace**: `v1` (configurable).
-*   **User**: `v1/User/Get.php` - Retrieve current user details.
-*   **Accounts**: `v1/Accounts.php` - List and manage user accounts.
+
+- **Namespace**: `v1` (configurable).
+- **User**: `v1/User/Get.php` - Retrieve current user details.
+- **Accounts**: `v1/Accounts.php` - List and manage user accounts.
 
 ## Documentation
-*   **Swagger/OpenAPI**: The project includes tools (`tools/swagger_validate.py`) and UI (`swagger-ui/`) to generate and display interactive API documentation.
+
+- **Swagger/OpenAPI**: The project includes tools (`tools/swagger_validate.py`) and UI (`swagger-ui/`) to generate and display interactive API documentation.

specs/architecture.md

@@ -1,35 +1,41 @@
 # System Architecture & Utilities
 
 ## Overview
+
 StartupAPI is built as a modular PHP application, designed for flexibility and rapid development. It employs a "Pluggable" architecture for core features and relies on established libraries for templating and frontend presentation.
 
 ## Core Architecture
 
 ### 1. Initialization & Bootstrapping
-*   **Entry Point**: `global.php` initializes the environment, loads configuration (`users_config.php`), and starts the session.
-*   **Main Class**: `StartupAPI` (`classes/StartupAPI.php`) serves as the central static accessor for global state and helper methods.
-*   **Autoloading**: Uses standard `require_once` patterns and Composer/library autoloaders where applicable.
+
+- **Entry Point**: `global.php` initializes the environment, loads configuration (`users_config.php`), and starts the session.
+- **Main Class**: `StartupAPI` (`classes/StartupAPI.php`) serves as the central static accessor for global state and helper methods.
+- **Autoloading**: Uses standard `require_once` patterns and Composer/library autoloaders where applicable.
 
 ### 2. Module System
-*   **Base Class**: `StartupAPIModule`.
-*   **Concept**: Functionality like Authentication, Payments, and Emailing are encapsulated in modules.
-*   **Registry**: `UserConfig::$all_modules` holds the list of active modules.
-*   **Extensibility**: Developers can create new modules by extending the base class and registering them in the config.
+
+- **Base Class**: `StartupAPIModule`.
+- **Concept**: Functionality like Authentication, Payments, and Emailing are encapsulated in modules.
+- **Registry**: `UserConfig::$all_modules` holds the list of active modules.
+- **Extensibility**: Developers can create new modules by extending the base class and registering them in the config.
 
 ### 3. Frontend & Templating
-*   **Engine**: **Twig** is the primary templating engine (`twig/`).
-*   **Themes**: Support for multiple themes (`themes/awesome`, `themes/classic`).
-*   **UI Framework**: Heavy reliance on **Bootstrap** (v2/v3) for responsive layout and components.
-*   **Assets**: `bootswatch` integration allows for easy visual customization.
+
+- **Engine**: **Twig** is the primary templating engine (`twig/`).
+- **Themes**: Support for multiple themes (`themes/awesome`, `themes/classic`).
+- **UI Framework**: Heavy reliance on **Bootstrap** (v2/v3) for responsive layout and components.
+- **Assets**: `bootswatch` integration allows for easy visual customization.
 
 ### 4. Utilities
-*   **Database Migration**: `dbupgrade.php` manages schema versioning and updates, ensuring the database stays in sync with the code.
-*   **Cron**: `cron.php` handles scheduled background tasks, essential for subscription billing and maintenance.
-*   **Dependency Check**: `depcheck.php` verifies that the server environment meets all requirements.
+
+- **Database Migration**: `dbupgrade.php` manages schema versioning and updates, ensuring the database stays in sync with the code.
+- **Cron**: `cron.php` handles scheduled background tasks, essential for subscription billing and maintenance.
+- **Dependency Check**: `depcheck.php` verifies that the server environment meets all requirements.
 
 ## File Structure
-*   `classes/`: Core logic and business entities.
-*   `modules/`: Pluggable functional blocks.
-*   `admin/`: Administrative interface logic.
-*   `themes/` & `view/`: Presentation layer.
-*   `controller/`: Request handling logic (MVC pattern).
+
+- `classes/`: Core logic and business entities.
+- `modules/`: Pluggable functional blocks.
+- `admin/`: Administrative interface logic.
+- `themes/` & `view/`: Presentation layer.
+- `controller/`: Request handling logic (MVC pattern).

specs/billing.md

@@ -1,51 +1,58 @@
 # Subscription & Billing Engine
 
 ## Overview
+
 The Subscription & Billing engine provides a flexible system for monetizing the application. It supports multiple subscription plans, varying payment schedules, and abstract payment gateways.
 
 ## Key Components
 
 ### 1. Plans
-*   **Class**: `Plan` (`classes/Plan.php`)
-*   **Definition**: Represents a subscription tier (e.g., "Basic", "Pro").
-*   **Attributes**:
-    *   `slug`: Unique identifier.
-    *   `name`: Display name.
-    *   `capabilities`: Feature flags enabled for this plan.
-    *   `downgrade_to_slug`: Fallback plan upon cancellation.
-    *   `grace_period`: Days to wait for payment before downgrading.
-*   **Hooks**: `account_activate_hook` and `account_deactivate_hook` for custom logic during plan changes.
+
+- **Class**: `Plan` (`classes/Plan.php`)
+- **Definition**: Represents a subscription tier (e.g., "Basic", "Pro").
+- **Attributes**:
+  - `slug`: Unique identifier.
+  - `name`: Display name.
+  - `capabilities`: Feature flags enabled for this plan.
+  - `downgrade_to_slug`: Fallback plan upon cancellation.
+  - `grace_period`: Days to wait for payment before downgrading.
+- **Hooks**: `account_activate_hook` and `account_deactivate_hook` for custom logic during plan changes.
 
 ### 2. Payment Schedules
-*   **Class**: `PaymentSchedule` (`classes/PaymentSchedule.php`)
-*   **Definition**: Defines how often and how much a user is charged for a plan.
-*   **Attributes**:
-    *   `charge_amount`: Cost per period.
-    *   `charge_period`: Frequency of billing (in days).
-    *   `is_default`: Default schedule for a plan.
+
+- **Class**: `PaymentSchedule` (`classes/PaymentSchedule.php`)
+- **Definition**: Defines how often and how much a user is charged for a plan.
+- **Attributes**:
+  - `charge_amount`: Cost per period.
+  - `charge_period`: Frequency of billing (in days).
+  - `is_default`: Default schedule for a plan.
 
 ### 3. Payment Engines
-*   **Class**: `PaymentEngine` (`classes/PaymentEngine.php`)
-*   **Role**: Abstract interface for payment providers.
-*   **Implementations**:
-    *   **Stripe**: Credit card processing.
-    *   **External**: Manual or off-platform payments.
-*   **Functionality**: Handles charge requests, recurrent billing setup, and webhook processing.
+
+- **Class**: `PaymentEngine` (`classes/PaymentEngine.php`)
+- **Role**: Abstract interface for payment providers.
+- **Implementations**:
+  - **Stripe**: Credit card processing.
+  - **External**: Manual or off-platform payments.
+- **Functionality**: Handles charge requests, recurrent billing setup, and webhook processing.
 
 ### 4. Account Billing State
-*   **Management**: Handled within the `Account` class.
-*   **States**:
-    *   Active plan.
-    *   Next plan (scheduled change).
-    *   Outstanding balance.
-*   **Lifecycle**:
-    *   **Upgrades/Downgrades**: Handled with proration logic.
-    *   **Cancellation**: Reverts to the "downgrade" plan (usually Free) after the current period or grace period.
+
+- **Management**: Handled within the `Account` class.
+- **States**:
+  - Active plan.
+  - Next plan (scheduled change).
+  - Outstanding balance.
+- **Lifecycle**:
+  - **Upgrades/Downgrades**: Handled with proration logic.
+  - **Cancellation**: Reverts to the "downgrade" plan (usually Free) after the current period or grace period.
 
 ## Configuration
-*   **Plan Definition**: Plans and schedules are defined in `users_config.php` passed to `Plan::init()`.
-*   **Gateways**: Credentials for providers like Stripe are configured in `UserConfig`.
+
+- **Plan Definition**: Plans and schedules are defined in `users_config.php` passed to `Plan::init()`.
+- **Gateways**: Credentials for providers like Stripe are configured in `UserConfig`.
 
 ## User Interface
-*   **Plans Page** (`plans.php`): Displays available plans and allows users to subscribe or switch.
-*   **Billing History**: Users can view past transactions and receipts (managed by `Account` and `TransactionLogger`).
+
+- **Plans Page** (`plans.php`): Displays available plans and allows users to subscribe or switch.
+- **Billing History**: Users can view past transactions and receipts (managed by `Account` and `TransactionLogger`).