Technische specificaties
Een moderne RAG-architectuur met AI-visie.
Architectuur in een oogopslag
ManualNinja is een multi-tenant RAG-applicatie met een Python-backend, een React SPA-frontend, een PostgreSQL-database en een Qdrant vectoropslag. Pdf's worden geparseerd, in stukken geknipt, geëmbed en als geciteerde antwoorden aangeboden via een chatinterface. Het platform bevat nu ook AI-visie voor beeldanalyse, OAuth social login en door Stripe aangedreven abonnementsfacturering.
Backend API
FastAPI + Uvicorn (Python 3.13). REST-eindpunten voor auth, handleidingen, chat, facturering en beheer. JWT-gebaseerde authenticatie met OAuth2.
Frontend
React 18 + Vite. Single-page application met chat-UI, beheerderspaneel, facturatieportal en superadmin-dashboard.
Database
PostgreSQL 17. Slaat organisaties, gebruikers, handleidingen, chatsessies, gebruikstracking en configureerbare instellingen op.
Vectoropslag
Qdrant 1.19. Semantisch zoeken over handleidingsfragmenten met organisatie-afgebakende filtering.
Embeddings
BAAI/bge-small-en-v1.5 (384 dimensies, CPU). Lokale inferentie — geen externe embedding-API-aanroepen.
LLM (tekst)
OpenAI-compatibele API. Standaardmodel: deepseek/deepseek-v3-0324. Configureerbaar via het superadmin-dashboard.
Een lokale AI gewenst voor extra beveiliging? Geen probleem. Neem contact op
LLM (visie)
Novita AI-visiemodel — google/gemma-3-27b-it. Analyseert geüploade afbeeldingen (apparaatlabels, foutcodeschermen, naamplaten) met OCR en gestructureerde extractie.
PDF-extractie
PyMuPDF (fitz). Paginaniveau chunking met behoud van metadata voor nauwkeurige citaties.
Web-URL import
Voeg handleidingen toe via URL in plaats van een PDF te uploaden. ManualNinja haalt de pagina op, volgt de paginering over alle subpagina's en extraheert de volledige handleidingstekst. SSRF-beveiligd (interne IP's geblokkeerd), 50 MB limiet per pagina, tot 200 pagina's per handleiding.
Authenticatie
JWT-tokens + Google OAuth 2.0 + LinkedIn OAuth 2.0 (OpenID Connect). E-mailverificatie met configureerbare SMTP.
Betalingen
Stripe — terugkerende abonnementen via Checkout, klantportal voor selfservice-beheer, webhook-gedreven levenscyclusgebeurtenissen.
Reverse proxy
Caddy — automatische HTTPS via Let’s Encrypt, HTTP/2, HTTP/3-ondersteuning.
Multi-tenancy & isolatie
Elke klantorganisatie krijgt een volledig geïsoleerde werkruimte:
- Organisatie-afgebakende gebruikers, handleidingen en chatsessies
- Qdrant-payloads bevatten org_id — vectorzoekopdracht wordt altijd gefilterd
- Op niveau gebaseerde limieten: vragen/maand, opslag, vraaggelengte, aantal handleidingen
- Alle integratiesleutels (Stripe, Google, LinkedIn, LLM, SMTP, reCAPTCHA) zijn per implementatie configureerbaar via de admin-UI
Beveiliging & gegevensbescherming
ManualNinja is gebouwd met beveiliging als eerste prioriteit. Elke laag van de stack is verhard om je gegevens en het vertrouwen van je klanten te beschermen.
End-to-end-versleuteling
Al het verkeer loopt over HTTPS met TLS 1.2/1.3 via Caddy met automatische Let’s Encrypt-certificaten. Geen plaintext-verbindingen geaccepteerd.
Veilige authenticatie
JWT-authenticatie met sterke secrets, bcrypt-wachtwoordhashing, OAuth 2.0 met CSRF-beschermde state-validatie en kortlevende exchange-codes in plaats van tokens in URL's.
Brute-force-bescherming
Inlog-pogingen beperkt (10 pogingen per 5 minuten per IP), aanmeldingslimiet (3 per IP per dag) en verplichte Google reCAPTCHA bij openbare aanmelding.
Multi-tenant-isolatie
Elke database-query en vectorzoekactie is beperkt tot organization_id. Cross-tenant datalek is onmogelijk — je handleidingen en chats zijn alleen van jou.
Veilige bestandsuploads
PDF uploads are validated by magic bytes, content type, and a 50 MB hard size limit. Files are stored with UUID names — no path traversal possible.
Geverifieerde webhooks
Stripe payment webhooks are always signature-verified. No unauthenticated payment events are ever processed — the system fails closed if the secret is missing.
Alleen interne services
De FastAPI-backend en Qdrant-vectordatabase binden alleen aan 127.0.0.1. Ze zijn nooit direct bereikbaar vanaf het internet — al het externe verkeer gaat via de Caddy reverse proxy.
E-mailverificatie
Aanmelding vereist e-mailverificatie met tijdgebonden tokens (24 uur geldig). Ongeverifieerde accounts kunnen niet inloggen.
Audit-logging
Alle admin- en superadmin-acties — organisatie-aanmaak, gebruikersbeheer, instellingswijzigingen — worden gelogd in een speciaal audit-spoor voor verantwoording en compliance.