From 947f299543dd2860218eb0f602cc0954aedcc175 Mon Sep 17 00:00:00 2001 From: Bjoern Runden Date: Thu, 17 Sep 2026 14:16:38 +0200 Subject: [PATCH] =?UTF-8?q?ignore=20erg=C3=A4nzt,=20continue=20(vscode=20a?= =?UTF-8?q?i=20plugin)=20hat=20noch=20eine=20context=20erhalten.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .continue/rules/CONTINUE.md | 113 ++++++++++++++++++++++++++++++++++++ .gitignore | 3 +- 2 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 .continue/rules/CONTINUE.md diff --git a/.continue/rules/CONTINUE.md b/.continue/rules/CONTINUE.md new file mode 100644 index 0000000..5855e05 --- /dev/null +++ b/.continue/rules/CONTINUE.md @@ -0,0 +1,113 @@ +# 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. diff --git a/.gitignore b/.gitignore index 10851d4..f1716e3 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,8 @@ env/ node_modules/ tsout/ kbp_crm*.js -App_Server/data/ +kbcrm/App_Server/data +#App_Server/data/ oidc-test/ .vibe/ .vibe-global/