mek-tech-consulting/ARCHITECTURE.md

# Mek-Tech Consultancy Framework — Architectuur

## Overzicht

Mek-Tech AI Consultancy Framework is een all-in-one consultancy CRM- en
managementplatform. Het biedt clientbeheer, trajecten (engagements),
facturatie, AI-gedreven advies, e-mailintegratie, backup/restore,
dashboarding en rapportage. Drie Python-microservices verzorgen
aanvullende functionaliteit: een visuele rack-editor, leadgeneratie
via scraping, en datakwaliteitscontroles.

Sinds v3.0 heeft de app een moderne **React 19 SPA** als primaire UI
(`/app`), gebouwd met Vite + Tailwind CSS v4. De klassieke EJS-interface
bestaat nog steeds op de oorspronkelijke paden. De SPA praat met een
JSON-API (`/api/spa`) die naast de bestaande EJS-routes draait.

## Tech Stack

| Laag | Technologie |
|------|-------------|
| **Frontend (nieuw)** | React 19 + Vite 6 + Tailwind CSS v4 + react-router 7 + recharts (`frontend/`) |
| **Backend** | Node.js 18 + Express 4 |
| **JSON API (nieuw)** | `routes/spa/` gemount op `/api/spa` (sessie-auth, 401-JSON) |
| **Database** | SQLite (via better-sqlite3) |
| **Templating (legacy)** | EJS — server-side rendered views |
| **Auth** | bcryptjs + express-session |
| **Microservices** | Python 3 + Flask (3 stuks) |
| **Container** | Docker + docker-compose |
| **Email** | IMAP (inbound) + Nodemailer (outbound) |

## Directory Structuur

```
consulting-framework/
├── server.js                 # Entrypoint Express app
├── frontend/                 # NIEUW: React 19 SPA (Vite)
│   ├── src/api.js            #   API-client (/api/spa, fmt helpers)
│   ├── src/auth.jsx          #   AuthContext (login/logout/me)
│   ├── src/components/       #   Layout (sidebar/topbar) + ui.jsx design system
│   └── src/pages/            #   24 pagina's (Dashboard, Clients, Time, ...)
├── public/spa/               # Gebouwde SPA (vite build output, geserveerd op /app)
├── routes/                   # ~30 route modules per domein (EJS, legacy)
│   ├── auth.js, users.js, password.js
│   ├── clients.js, engagements.js, projects.js
│   ├── invoices.js, finance.js, time.js
│   ├── dashboard.js, reports.js, report.js
│   ├── ai.js, consulting.js, assess.js
│   ├── backup.js, calendar.js, email.js
│   ├── settings.js, search.js, notifications.js
│   ├── infrastructure.js, networking.js, racks.js
│   ├── architecture.js, sizing.js, quality.js
│   ├── market.js, integrations.js, audit.js, api.js
│   └── spa/                  # NIEUW: JSON API voor de SPA
│       ├── index.js          #   mount + sessie-guard + /dashboard aggregatie
│       ├── auth.js           #   POST /auth/login, /auth/logout, GET /auth/me
│       ├── crm.js            #   clients, notes, engagements, tasks
│       ├── finance.js        #   time entries, invoices, finance-stats
│       ├── infra.js          #   racks, rack devices, networking, diagrams
│       └── misc.js           #   calendar, projects, notifications, search,
│                             #   settings, users, audit, backup, market, ai, email
├── lib/                      # Bedrijfslogica
│   ├── ai.js                 # AI provider interface
│   ├── backup.js             # Backup/restore engine
│   ├── consulting-hub.js     # Consultancy hub logica
│   ├── crm.js                # CRM kernel
│   ├── nav.js                # Navigatieopbouw (legacy EJS)
│   ├── rack-diagram.js       # Rack diagram generator
│   └── services.js           # Services registry
├── views/                    # EJS templates (~40+, legacy UI)
├── data/                     # SQLite DB, JSON configs
├── locales/                  # i18n (en.json, nl.json)
├── public/                   # Static assets (icons, SW, spa build)
├── python-editor/            # Microservice 1: diagram editor
├── python-leadgen/           # Microservice 2: lead scraping
├── python-quality/           # Microservice 3: data quality
├── Dockerfile                # Node.js productie-image
├── docker-compose.yml        # 5 services orchestration
└── package.json
```

## Data Flow

### Nieuwe SPA (primair)

```
Browser → React SPA (/app, static uit public/spa)
            └── fetch /api/spa/* (sessie-cookie)
                  ├── routes/spa/ (JSON, 401 bij geen sessie)
                  ├── lib/ + db.js (business logic, SQLite)
                  └── Python microservices (via proxy's waar nodig)
```

- SPA login: `POST /api/spa/auth/login` → express-session cookie
- Globale guard in server.js: `/api/*` zonder sessie → **401 JSON**
  (nooit redirect); browser-routes zonder sessie → redirect `/login` (legacy)
- `/app` is publiek bereikbaar; de SPA toont zelf een loginpagina
- Vite dev-server proxied `/api` naar de productieserver (zie frontend/vite.config.js)

### Legacy EJS (behouden)

```
Browser → Express (server.js)
            ├── routes/ (auth check, params)
            ├── lib/ (business logic, DB queries)
            ├── data/ (SQLite reads/writes)
            └── views/ (EJS render → HTML response)
```

## Microservices

| Service | Poort | Map | Functie |
|---------|-------|-----|---------|
| **Python Designer** | 3001 | `python-editor/` | Visuele rack diagram editor — HTML/CSS designer-tool |
| **Python Leadgen** | 3003 | `python-leadgen/` | Leadgeneratie: scrapet websites, extraheert contactgegevens, slaat op in DB |
| **Python Quality** | 3002 | `python-quality/` | Data quality checks: valideert datasets, genereert kwaliteitsrapporten |

Elke microservice heeft een eigen Dockerfile en draait als los Flask-appje.

## Deployment

### Docker Compose (5 services)

```yaml
services:
  consulting:       # Node.js :3000 (hoofd-app)
  python-designer:  # Flask :3001
  python-quality:   # Flask :3002
  python-leadgen:   # Flask :3003
  showcase:         # apart project op :3010
```

Alle services draaien op `0.0.0.0` en zijn bereikbaar op het LAN.

### SPA ontwikkelen & deployen

```bash
cd frontend
npm install
npm run dev        # dev-server op :5173, proxied /api naar 192.168.1.247:3000
npm run build      # bouwt naar frontend/dist
```

Deploy = build kopiëren naar `public/spa/` en committen; de container
krijgt die via de bestaande `./public` bind-mount binnen. Daarna op de
server: `git pull && docker compose restart consulting`.

### Recovery (bij crash)

1. `git clone` vanuit Gitea: `http://git.211:3000/mo/mek-tech-consulting.git`
2. `.env` bestand aanmaken op basis van `homelab-configs/.env.example`
3. `docker compose up -d` — alle containers starten
4. SQLite DB (`data/consulting.db`) kan gerestored worden uit `data/backups/`