From fd8976fedcec8b5390d962a2925ee3baae87b36c Mon Sep 17 00:00:00 2001
From: Patrik Oberschmid <p.oberschmid@cp-solutions.at>
Date: Fri, 10 Apr 2026 11:09:46 +0200
Subject: [PATCH] =?UTF-8?q?Claude.md=20f=C3=BCr=20alle=20drinnen?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..f551917
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+3CX TAPI is a dual-component integration that bridges the 3CX VoIP telephony web client with a CPA project management suite (CP Solutions) and a time tracking system (ZeitConsens). It is deployed as a Tampermonkey UserScript (client) communicating with a self-hosted ASP.NET Core API (server).
+
+## Repository Structure
+
+```
+/
+├── client/          # TypeScript UserScript (Tampermonkey)
+├── server/          # C# ASP.NET Core 10.0 REST API
+└── 3CX_TAPI.user.js # Built distribution file (committed artifact)
+```
+
+## Client Commands
+
+All commands run from `client/`:
+
+```bash
+npm run build    # Production webpack build → dist/3CX TAPI.prod.user.js
+npm run dev      # Development build with live reload
+npm run lint     # ESLint on TypeScript/JavaScript sources
+npm run anylize  # Build with webpack-bundle-analyzer
+```
+
+After building, copy the output to the repo root:
+```bash
+cp "client/dist/3CX TAPI.prod.user.js" 3CX_TAPI.user.js
+```
+
+The root `3CX_TAPI.user.js` is the committed distribution artifact installed via Tampermonkey.
+
+## Server Commands
+
+All commands run from `server/src/CPATapi.Server/`:
+
+```bash
+dotnet build                              # Debug build
+dotnet build -c Release                   # Release build
+dotnet publish -c Release -o /app/publish # Publish for deployment
+docker build -f Dockerfile -t cpatapi-server .  # Docker image
+```
+
+No automated tests exist — only manual testing and client-side linting.
+
+## Architecture
+
+### Client (`client/src/`)
+
+A Tampermonkey UserScript injected into the 3CX web UI at `https://192.168.0.154:5001/*` and `https://cpsolution.my3cx.at:5001/*`. Entry point: `src/index.js`.
+
+Four main modules:
+
+- **`search.ts`** — Autocomplete contact lookup box injected near the call button. Debounces input and calls `GET /search?query=...`. On selection, dials the contact via 3CX.
+- **`call-history.ts`** — Monitors 3CX call history entries, does reverse lookup via `GET /callerid/{number}`, and adds a "PM Zeitbuchung" button that opens the Domizil PM time booking system with pre-filled metadata (contact ID, timestamp, duration).
+- **`call-notification.ts`** — Enriches incoming call GM notifications with contact name/medium fetched from TAPI directory.
+- **`status.ts`** — Polls `GET /availability/{user}` every 30 seconds and auto-syncs 3CX presence status with ZeitConsens login state (odd stamp count = logged in, even = logged out). User settings (username, enabled, status IDs) persist via `GM.setValue`.
+
+API base URL is configured in `src/config.ts` (`Config.tapi_server_url`).
+UserScript metadata (match URLs, GM grants, CORS) is in `config/metadata.cjs`.
+
+### Server (`server/src/CPATapi.Server/`)
+
+ASP.NET Core 10.0 Web API using Dapper for SQL Server queries. Deployed as a Docker Linux container exposing port 8080.
+
+**API Endpoints:**
+
+| Endpoint | Description |
+|---|---|
+| `GET /search?query=` | Splits query into terms, searches `CP_TAPI_DIRECTORY` by name or number (top 10) |
+| `GET /contact` | Returns all contacts from `CP_TAPI_DIRECTORY` |
+| `GET /callerid/{number}` | Reverse lookup: extracts last 5 digits, returns first matching contact or 404 |
+| `GET /availability/users` | Lists active users from `MA_DATEN` |
+| `GET /availability/{user}` | Counts today's stamps in `BU` table; odd count = logged in |
+
+**Data flow:** Controllers → Repository interfaces → Dapper repositories → SQL Server.
+
+Two connection strings in `appsettings.json`:
+- `"Tapi"` — contacts database (`CP_TAPI_DIRECTORY` table)
+- `"ZeitConsens"` — time tracking database (`MA_DATEN`, `BU` tables)
+
+Logging uses Serilog with client IP, correlation ID, and user-agent enrichment.