# kbcrm Project Guide

Welcome to the **kbcrm** project! This guide provides an overview of the project's structure, technologies, and development workflow. It is designed to help you understand how to navigate and contribute to this application effectively.

## 1. Project Overview

**kbcrm** is a Customer Relationship Management application that features a decoupled architecture with a Python/Flask backend and a TypeScript/Mithril.js frontend. It delegates authentication to an external Identity Provider (Zitadel) using OIDC, while managing local user data and roles via a SQLite database.

### Key Technologies

*   **Backend:** Python, Flask 2.x, SQLAlchemy (SQLite)
*   **Authentication:** Authlib, Zitadel (IdP)
*   **Production Server:** Waitress
*   **Frontend:** TypeScript, Mithril.js
*   **Infrastructure:** Docker, Nginx

### Architecture

The application follows a client-server architecture. The `App_Server` contains the backend API and business logic, serving REST endpoints. The `Client` directory holds the source code for the Single Page Application (SPA), which is built into static JavaScript files. These static files are served by an Nginx server, configured in the `NGINX_Server` directory.

## 2. Getting Started

### Prerequisites

*   Python 3.11+
*   Node.js and npm (for building the frontend)
*   Docker and Docker Compose (for containerized deployment/development)

### Local Development Setup (Backend)

1.  **Create and activate a virtual environment:**
    ```bash
    cd App_Server
    python3 -m venv venv
    source venv/bin/activate
    ```
2.  **Install dependencies:**
    ```bash
    pip install -r root/requirements.txt
    ```
3.  **Configuration:**
    Copy the `.env.example` to `.env` (in the project root) and configure your Zitadel credentials and other environment variables.
4.  **Initialize Database:**
    The database schema is initialized using scripts in the application. (Refer to the `checkdb.py` mechanisms for DB migrations).
5.  **Run the application:**
    ```bash
    python root/runserver.py
    ```
    *Note: The exact command might depend on how `runserver.py` is configured to launch the Flask app.*

### Local Development Setup (Frontend)

1.  **Install Node dependencies:**
    ```bash
    cd Client
    npm install
    ```
2.  **Build the client:**
    ```bash
    npm run build
    ```
    This command compiles TypeScript and uses Rollup to bundle the JavaScript files, placing the output in `NGINX_Server/html/static/`.

## 3. Project Structure

*   `App_Server/`: Backend application directory.
    *   `root/`: Contains the core Python application code.
        *   `auth/`: User management and authentication logic.
        *   `routes/`: Flask route definitions.
        *   `db.py`: Database connection setup.
    *   `data/`: SQLite database files.
*   `Client/`: Frontend SPA source code.
    *   `Components/`: Mithril.js GUI components.
        *   `widgets/`: Reusable UI elements (inputs, buttons, etc.).
        *   `models/`: TypeScript data models and API calls.
*   `NGINX_Server/`: Configuration for the Nginx web server.
    *   `html/static/`: Contains the compiled CSS and JS files for the frontend.
*   `ai-context/`: Guidelines and rules for AI assistants working on this project.
*   `docker-compose.*.yaml`: Docker compose configurations for different environments.

## 4. Development Workflow

### Frontend Development (TypeScript & Mithril.js)

*   **Responsive Design:** Use `w3.css` classes (located in `NGINX_Server/html/static/w3.css`) for layout and responsive design. Wrap view containers with `w3-container w3-auto`.
*   **Theming:** Prefer classes from `app-theme.css` for colors.
*   **Icons:** Use Google Material Icons from the `Google_Symbols.woff2` file.
*   **Mithril.js Components:**
    *   When using `m.ClosureComponent`, omit the closure parameter (`() =>`) and access attributes exclusively via the `vnode` in lifecycle hooks (`oninit`, `view`, etc.).
    *   Avoid reading `attrs` directly in the closure scope, as they will be stale on redraws.
    *   Format long attribute lists cleanly.
*   **API Calls:** Every `m.request` must append `.catch((e) => showServerError(e))` to display server errors globally. Navigation logic (`m.route.set`) should reside in the `.then` block.
*   **Data Models:** Create distinct `.ts` files for data models in `Client/Components/models` (or `Client/Models` as per guidelines). Perform API calls in these files. Edit forms should fetch fresh data by ID on initialization, rather than relying on cached list data.
*   **Build Process:** After editing files in `Client/`, always run `npm run build` (or the specific build command) to update the bundles in `NGINX_Server/html/static/`. *Do not edit files in `Client/tsout/` or the compiled `.js` files in `NGINX_Server`.*

### Backend Development (Python & Flask)

*   **Project Isolation:** Projects are user-specific. Always filter read and write operations based on `projekt_users`.
    *   Use `_get_visible_user_id()` for read endpoints to filter by the current user (admins see all).
    *   Use `_require_projekt_access(projekt_id)` before write operations (create/update/delete) to enforce access control. Return a 404 error if access is denied to avoid revealing project existence.
*   **Database Migrations:** Changes to the schema must be handled via `_db_Vxx_xx` functions in `checkdb.py`. **All migrations must be idempotent.** Use `IF NOT EXISTS` for indexes and check for column existence before adding them.

### Code Style and Conventions

*   **Documentation:** All Python modules (`.py`) and Jinja2 templates (`.html`) must start with a standardized header containing metadata (`Author:`, `Date:`, `Purpose:`, etc.). Python docstrings are used by Sphinx to generate documentation.
*   **Comments:** Write meaningful comments in German.

## 5. References

*   **Mithril.js Documentation:** https://mithril.js.org/
*   **Flask Documentation:** https://flask.palletsprojects.com/
*   **Authlib Documentation:** https://docs.authlib.org/
*   See the `ai-context/` directory for detailed structural and operational guidelines.