114 lines
6.0 KiB
Markdown
114 lines
6.0 KiB
Markdown
# 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.
|