docs: ARCHITECTURE.md met volledige projectstructuur

2026-07-12 21:59:55 +00:00
parent 18921c021b
commit b2d6a9a2f6
1 changed files with 111 additions and 0 deletions
@@ -0,0 +1,111 @@
+# 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.
+
+## Tech Stack
+
+| Laag | Technologie |
+|------|-------------|
+| **Backend** | Node.js 18 + Express 4 |
+| **Database** | SQLite (via better-sqlite3) |
+| **Templating** | 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
+├── routes/                   # ~30 route modules per domein
+│   ├── auth.js, 2fa.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, automations.js
+│   ├── audit.js, api.js
+│   └── views/               # Sub-route EJS views
+├── 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
+│   ├── rack-diagram.js       # Rack diagram generator
+│   └── services.js           # Services registry
+├── views/                    # EJS templates (~40+)
+│   ├── index.ejs, login.ejs, dashboard.ejs
+│   ├── client-*.ejs, engagement-*.ejs
+│   ├── invoice-*.ejs, finance.ejs
+│   └── partials/             # Herbruikbare EJS partials
+├── data/                     # SQLite DB, JSON configs
+├── locales/                  # i18n (en.json, nl.json)
+├── public/                   # Static assets (icons, SW)
+├── 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
+
+```
+Browser → Express (server.js)
+            ├── routes/ (auth check, params)
+            ├── lib/ (business logic, DB queries)
+            ├── data/ (SQLite reads/writes)
+            └── views/ (EJS render → HTML response)
+```
+
+- Alle routes doorlopen `server.js` voor sessie- en middleware setup
+- Business logic zit in `lib/`, niet in routes
+- Templates in `views/` worden server-side gerenderd
+- Python microservices worden aangeroepen via HTTP van de Node.js app
+
+## 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.
+
+### 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/`