Add SaaS Rebuild Analysis Documents

agent/analysis/ARCHITECTURE.md

@@ -0,0 +1,103 @@
+# Target Architecture
+
+This document outlines the proposed architecture for the rebuilt Nail Studio SaaS application. The design is guided by the decisions made in the `TRUTH_TABLE.md` and aims to address the shortcomings of the original implementation.
+
+## 1. Guiding Principles
+
+- **Clarity over Cleverness:** The new architecture will prioritize readability and maintainability.
+- **Single Source of Truth (SSOT):** Every piece of business logic and data should have one, and only one, authoritative home.
+- **Service-Oriented:** Business logic will be decoupled from the web framework (Flask) and data layer (SQLAlchemy) where possible.
+- **Testability:** The architecture must be easy to test, with clear separation between components.
+
+## 2. Core Components
+
+The application will be structured into three primary layers: the **Web Layer**, the **Service Layer**, and the **Data Layer**.
+
+### 2.1. Web Layer (Flask)
+
+- **Responsibility:** Handling HTTP requests and responses. This layer should contain minimal business logic.
+- **Structure:**
+  - **Blueprints:** The existing blueprint structure will be retained and reinforced. Each blueprint will handle a specific domain (e.g., `transactions`, `users`, `reports`).
+  - **Routes (`routes.py`):** Route functions will be responsible for:
+    1. Parsing incoming request data (e.g., from forms or JSON bodies).
+    2. Calling the appropriate **Service Layer** function(s) to perform business operations.
+    3. Handling authorization checks via a unified decorator.
+    4. Rendering templates or returning JSON responses based on the results from the Service Layer.
+  - **Forms (`forms.py`):** WTForms will continue to be used for server-side validation.
+
+### 2.2. Service Layer (New)
+
+- **Responsibility:** This is the heart of the new architecture. It will contain all the business logic that was previously scattered between model properties and route functions.
+- **Structure:**
+  - A new `app/services` directory will be created.
+  - Each service will be a Python class or module focused on a specific domain.
+  - **Example Services:**
+    - `SalaryService`: Will contain the unified logic for calculating master salaries, handling all modes (`percent`, `fixed`, `mixed`). This fixes the "Badly Implemented Domain Truth" identified in the Truth Table.
+    - `ReportingService`: Will generate complex reports by querying the data layer.
+    - `TransactionService`: Will handle the creation, modification, and deletion of transactions, ensuring all related business rules are followed.
+- **Benefits:**
+  - **Decoupling:** The business logic is no longer tied to Flask routes or SQLAlchemy models.
+  - **Testability:** Services can be unit-tested in isolation, without needing a full web request context.
+  - **Reusability:** The same service can be used by web routes, background jobs, or command-line scripts.
+
+### 2.3. Data Layer (SQLAlchemy)
+
+- **Responsibility:** Defining the structure of the data and interacting with the database.
+- **Structure:**
+  - **Models (`app/models`):** SQLAlchemy models will be treated as pure data containers.
+    - They will contain table definitions, columns, and relationships.
+    - **NO business logic.** Properties like `Transaction.master_salary` will be removed and their logic moved to the `SalaryService`.
+    - Helper properties for simple formatting (e.g., `total_amount`) are acceptable.
+  - **Repositories (Optional but Recommended):** For more complex queries, the Repository Pattern can be introduced to encapsulate data access logic, further separating the Service Layer from direct SQLAlchemy query syntax.
+
+## 3. Key Architectural Decisions
+
+### 3.1. Unified Authorization System
+
+- The legacy `role` string on the `User` model will be **eliminated**.
+- The system will rely **exclusively** on the `Role` and `Permission` models.
+- A custom Flask decorator (e.g., `@permission_required('edit_transaction')`) will be created to enforce permissions at the route level, making access control explicit and easy to audit.
+
+### 3.2. Configuration and Initialization
+
+- The `create_app` factory pattern will be maintained.
+- Environment variables will be the primary method for configuration to follow 12-Factor App principles.
+
+### 3.3. Refined Data Models
+
+- **`Source` Model:** Will be updated with a boolean flag `is_smm_source` to replace the hardcoded string matching, as decided in the Truth Table.
+- All models will be reviewed for clarity and normalization.
+
+## 4. Diagram of Proposed Architecture
+
+```
++------------------------------------------------------------------+
+|      Web Layer (Flask Blueprints)                                |
+|------------------------------------------------------------------|
+| - Handles HTTP Requests/Responses                                |
+| - Validates Input (Forms)                                        |
+| - Calls Service Layer for business logic                         |
+| - Renders Templates / Returns JSON                               |
+| - Enforces Permissions with Decorators                           |
+|      (@permission_required)                                      |
++--------------------------+---------------------------------------+
+                           |
+                           v
++--------------------------+---------------------------------------+
+|      Service Layer (Plain Python)                                |
+|------------------------------------------------------------------|
+| - Contains all Business Logic (e.g., SalaryService)              |
+| - Orchestrates Data Layer operations                             |
+| - Decoupled from Web and Data specifics                          |
+| - Highly Testable                                                |
++--------------------------+---------------------------------------+
+                           |
+                           v
++--------------------------+---------------------------------------+
+|      Data Layer (SQLAlchemy Models)                              |
+|------------------------------------------------------------------|
+| - Defines Data Schema (Tables, Columns, Relationships)           |
+| - Models are simple data containers (no business logic)          |
+| - (Optional) Repositories for complex query encapsulation        |
++------------------------------------------------------------------+
+```

agent/analysis/DOMAIN_MAP.md

@@ -0,0 +1,73 @@
+# Domain Map
+
+This document outlines the core business concepts (the domain) of the Nail Studio application, derived from the existing codebase.
+
+## 1. Core Entities
+
+### 1.1. Transaction
+- **Description:** The central and most important entity in the system. It represents a single customer visit or sale.
+- **Key Attributes:** Date, Master, Services Rendered, Items Sold, Total Amount, Payment Method, Client Source.
+- **Relationships:**
+  - Belongs to one `Master`.
+  - Can have many `Services`.
+  - Can have many `TransactionItems` (products sold).
+  - Belongs to one `Source`.
+  - Belongs to one `PaymentMethod`.
+
+### 1.2. Master
+- **Description:** An employee who performs services for clients (e.g., a nail technician). They are the primary revenue generators.
+- **Key Attributes:** Name, Commission Percent (for services), Sales Commission Percent (for products), Salary Mode (`percent`, `fixed`, `mixed`), Fixed Daily Rate.
+- **Relationships:**
+  - Can have many `Transactions`.
+  - Can be linked to one `User` account for system access.
+
+### 1.3. User & Access Control
+- **Description:** An individual who can log in to the application. Their access is governed by roles and permissions.
+- **Key Concepts:**
+  - **User:** The login account (username, password).
+  - **Role:** A template defining a set of permissions (e.g., "Senior Admin", "Master", "SMM").
+  - **Permission:** A specific right to perform an action (e.g., "view_financial_reports", "edit_users").
+- **Relationships:**
+  - A `User` has one `Role`.
+  - A `Role` grants multiple `Permissions`.
+  - A `User`'s permissions can be individually overridden.
+  - A `User` can be linked to one `Master` profile.
+- **Note:** The system currently has a hybrid implementation, with both a simple `role` string and a more structured `Role`/`Permission` model.
+
+### 1.4. Financial & Inventory Entities
+- **Service:** A specific service offered by the studio (e.g., "Gel Manicure"). It has a price.
+- **Shelf Item / Transaction Item:** A physical product sold by the studio. `ShelfItem` is the catalog entry, and `TransactionItem` is the instance of that item within a `Transaction`.
+- **Expense:** A record of a business cost (e.g., rent, supplies). It has an amount, date, and category.
+- **Daily Balance:** A record of the cash on hand at the beginning of a business day.
+
+### 1.5. Supporting Entities (Parameters)
+- **Source:** The source of a client (e.g., "Instagram", "Walk-in"). Used for marketing analytics and commission calculations.
+- **Payment Method:** How a transaction was paid for (e.g., "Cash", "Card"). Can have an associated fee.
+- **Expense Category:** A category for an `Expense` (e.g., "Rent", "Supplies").
+- **Discount Reason:** The reason a discount was applied to a transaction.
+
+## 2. Core Business Processes
+
+### 2.1. Recording a Transaction
+- An administrator or master records a client visit.
+- They select the `Master`, the `Services` performed, and any `ShelfItems` sold.
+- They input the payment details (`PaymentMethod`, amount, discounts).
+- The system saves this as a `Transaction`.
+
+### 2.2. Master Salary Calculation
+- This is a critical and complex process.
+- The salary is calculated per-`Transaction`.
+- The logic depends on the `Master.salary_mode`:
+  - **Percent:** `Transaction.real_amount * Master.commission_percent` + commissions from product sales.
+  - **Fixed:** A flat `Master.fixed_daily_rate` is applied (logic for this seems to be in reporting, not the model).
+  - **Mixed:** A combination of the fixed rate and percentage-based commissions.
+- The `Transaction.master_salary` property calculates the percentage-based portion for a single transaction.
+
+### 2.3. Financial Reporting
+- The system generates reports based on aggregated `Transaction` and `Expense` data.
+- Key metrics include: Total Income, Total Expenses, Net Profit, Average Check.
+- Reports are often filtered by date ranges and can be specific to a `Master`.
+
+### 2.4. User Access Management
+- Users are assigned roles that restrict their view and actions.
+- For example, a `Master` can only see their own transactions and salary, while an `Owner` can see all financial data.

agent/analysis/PROJECT_SCAN.md

@@ -0,0 +1,45 @@
+# Project Scan
+
+## 1. Overview
+
+This document provides a high-level technical overview of the existing Nail Studio project. The analysis is based on a static examination of the repository's file structure, key source code files, and configuration.
+
+## 2. Core Technology Stack
+
+- **Backend Framework:** Flask
+- **Database ORM:** Flask-SQLAlchemy
+- **Authentication:** Flask-Login
+- **Forms:** Flask-WTF
+- **Database Migrations:** Flask-Migrate
+- **Dependencies:** Key libraries include `qrcode`, `pillow`, `pytest`, and `waitress`. All dependencies are listed in `requirements.txt`.
+
+## 3. Project Structure
+
+The project follows a modular, blueprint-based architecture.
+
+- **`run.py`**: The main entry point for the application. It initializes the Flask app and runs it.
+- **`config.py`**: Contains application configuration, including database URIs and default credentials.
+- **`app/`**: The main application package.
+  - **`__init__.py`**: Contains the `create_app` factory function, which initializes extensions and registers blueprints.
+  - **`models/`**: Defines all SQLAlchemy database models. This is the source of truth for the data structure.
+  - **`main/`**: The main blueprint, containing the primary dashboard route (`/`).
+  - **`auth/`**: Handles user authentication (login, logout).
+  - **`transactions/`, `expenses/`, `reports/`, etc.**: Feature-specific blueprints, each containing its own routes and logic.
+  - **`forms/`**: Contains WTForms definitions for data validation and input.
+  - **`utils.py`**: Utility functions, including database initialization logic.
+- **`migrations/`**: Contains database migration scripts generated by Flask-Migrate.
+- **`templates/`**: Contains Jinja2 HTML templates for the user interface.
+- **`tests/`**: Contains application tests (structure suggests Pytest).
+- **`Dockerfile`, `docker-compose.yml`, `render.yaml`**: Files indicating support for containerization (Docker) and deployment on cloud platforms (Render).
+
+## 4. Key Architectural Observations
+
+- **Modular Design:** The use of Flask Blueprints is a good architectural choice, separating concerns by feature.
+- **Centralized Models:** All data models are defined within the `app/models` package, providing a clear and centralized view of the data schema.
+- **Hybrid Auth System:** The `app/models/user.py` file reveals a hybrid authentication/authorization system. It includes both a legacy string-based `role` field and a more robust, newer system based on `Role` and `Permission` models with JSON-based permission overrides. This indicates a system in transition.
+- **Business Logic in Models:** Critical business logic, such as the `master_salary` calculation, is implemented as a property within the `Transaction` model. This is a common pattern but can lead to complex models.
+- **Database:** The project is configured to use a database managed by SQLAlchemy and Flask-Migrate, which is standard for Flask applications.
+
+## 5. Initial Assessment
+
+The project is a non-trivial Flask application with a solid, if partially refactored, foundation. The blueprint structure is sound, but the hybrid nature of the permission system is a key area of complexity that needs to be addressed in the rebuild. The domain logic appears to be deeply embedded within the ORM models.

agent/analysis/TRUTH_TABLE.md

@@ -0,0 +1,18 @@
+# Truth Table
+
+This table classifies each major concept from the old project to determine its business value and decide its fate in the new system.
+
+| Concept | Where It Appears | Why It Exists (Business Explanation) | Classification | Decision & Justification |
+| :--- | :--- | :--- | :--- | :--- |
+| **Transaction** | `app/models/transaction.py` | Represents a client visit or sale, the fundamental unit of revenue. | CORE DOMAIN TRUTH | **KEEP.** This is the central entity of the entire application. |
+| **Master** | `app/models/master.py` | Represents a service provider (employee) who generates revenue. | CORE DOMAIN TRUTH | **KEEP.** Essential for tracking sales, services, and calculating salaries. |
+| **Master Salary Calculation (in model)** | `Transaction.master_salary` property | To calculate the percentage-based portion of a master's pay for a single transaction. | DOMAIN TRUTH, BADLY IMPLEMENTED | **REWRITE.** The logic is domain truth, but its implementation is incomplete and misplaced. It only handles the percentage part, ignoring the fixed-rate salary, which is handled elsewhere (in reports). The new system must have a unified, single source of truth for all salary calculations, likely in a dedicated service layer, not the model property. |
+| **Hybrid RBAC System** | `app/models/user.py` (legacy `role` field vs. new `Role`/`Permission` models) | The system evolved from a simple role string to a more flexible permissions model, but the old system was never fully removed. | ARCHITECTURAL ERROR | **REWRITE.** The existence of two parallel systems for authorization is a major source of confusion and potential bugs. The new system will use **only** the structured `Role` and `Permission` models. The legacy `role` string will be dropped entirely after a data migration. |
+| **User-Master Link** | `User.master_id` foreign key | To connect a user's login account to their employee profile, allowing masters to log in and see their own stats. | CORE DOMAIN TRUTH | **KEEP.** This is a critical link for role-based access control and personal dashboards. |
+| **Service** | `app/models/params.py` | Defines a service that can be sold (e.g., "Manicure"). | CORE DOMAIN TRUTH | **KEEP.** A fundamental part of a transaction. |
+| **Shelf Item / Product Sale** | `app/models/inventory.py`, `app/models/transaction.py` | Represents physical goods that can be sold, with their own commission structures. | CORE DOMAIN TRUTH | **KEEP.** Represents a distinct and important revenue stream for the business. |
+| **Expense Tracking** | `app/models/finance.py` | To record business expenses for profit/loss calculation. | CORE DOMAIN TRUTH | **KEEP.** Essential for any financial accounting. |
+| **Client Source Tracking** | `app/models/params.py` | To track marketing channels (e.g., Instagram, Walk-in) and calculate potential commissions for partners. | CORE DOMAIN TRUTH | **KEEP.** Provides valuable business intelligence for marketing efforts. |
+| **Daily Balance** | `app/models/finance.py` | To track the opening cash balance for the day. | CORE DOMAIN TRUTH | **KEEP.** A standard and necessary feature for daily cash flow management. |
+| **Hardcoded SMM Logic** | `app/main/routes.py` (line 80, `Source.name.ilike('%инст%')`) | To identify new clients coming from specific social media sources for SMM dashboards. | TEMPORARY WORKAROUND | **REWRITE.** This is a brittle, temporary solution. The domain truth is "tracking SMM performance," but the implementation is poor. The new system should use a more robust mechanism, like a dedicated `is_smm_source` boolean flag or a tag system on the `Source` model, to avoid hardcoded strings in business logic. |
+| **Soft Deletes** | `SoftDeleteMixin` in `app/models/base.py` | To allow data to be "deleted" without actually removing it from the database, preserving historical integrity. | CORE DOMAIN TRUTH | **KEEP.** This is a critical business requirement for a system of record, preventing accidental data loss and preserving audit trails. |