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)

Create and activate a virtual environment:

cd App_Server
python3 -m venv venv
source venv/bin/activate

Install dependencies:
```
pip install -r root/requirements.txt
```
Configuration: Copy the .env.example to .env (in the project root) and configure your Zitadel credentials and other environment variables.
Initialize Database: The database schema is initialized using scripts in the application. (Refer to the checkdb.py mechanisms for DB migrations).
Run the application:
```
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)

Install Node dependencies:
```
cd Client
npm install
```
Build the client:
```
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.

6.0 KiB Raw Blame History