# AILIXIR Architecture & Component Documentation Last updated: 2026-05-29 This document provides detailed diagrams and per-component explanations for the AILIXIR BackEnd. It is intended for developers and SREs onboarding onto the project and for inclusion in production runbooks. Contents -------- - System-level architecture (diagram + explanation) - Data flow and request lifecycle - Per-service component diagrams and responsibilities - Laravel (orchestration) - ADMET inference (FastAPI) - Drug Repurposing (FastAPI) - Chemical RAG (FAISS + RAG) - Environment variables & configuration locations - Deployment notes and scaling considerations - Troubleshooting checkpoints System-level architecture (Mermaid) ---------------------------------- ```mermaid flowchart LR subgraph CLIENTS [Clients] A[Web UI / Frontend] B[External Integrations / APIs] end subgraph DOCKER_NET [Docker network: ailixir] direction TB LAR(Laravel API) Q(Queue Worker) MYSQL[(MariaDB)] ADMET(ADMET Inference) DRUG(Drug Repurposing) CRAG(Chemical RAG) end A -->|HTTP| LAR B -->|HTTP| LAR LAR -->|DB| MYSQL LAR -->|enqueue| Q LAR -->|AI calls| ADMET LAR -->|AI calls| DRUG LAR -->|AI calls| CRAG ADMET -->|models stored on disk| ADMET CRAG -->|FAISS index on volume| CRAG DRUG -->|model artifacts| DRUG ``` Explanation ----------- - Clients (web, CLI, external services) interact with the `laravel` orchestration API. The Laravel layer handles authentication, request validation, and orchestration of multi-step workflows. - Long-running tasks are delegated to the `queue` worker via Laravel's queue system. The queue worker communicates with the same Laravel codebase and uses the internal database for job bookkeeping. - AI microservices are independent FastAPI services: `admet`, `drug-repurposing`, and `chemical-rag`. Laravel calls these services over the internal Docker network by service name. - Persistent storage: `mysql` holds application state, users, and job metadata; AI services use container volumes for model artifacts and FAISS indexes. Request lifecycle — typical screening flow --------------------------------------- 1. Client POSTs request to Laravel endpoint (e.g., run screening). 2. Laravel validates and creates a job record in MySQL and either performs synchronous work or enqueues a background job. 3. Background job triggers calls to AI services in parallel or sequence depending on pipeline stage: - `drug-repurposing` to run virtual screening - `admet` to score ADMET properties - `chemical-rag` to fetch similar compounds or augment results 4. AI services return raw predictions to Laravel which aggregates results, persists summary, and notifies the client. Per-service diagrams & responsibilities -------------------------------------- 1) Laravel (orchestration) ```mermaid flowchart TD In[HTTP Request] Auth[Auth Layer] Validate[Validation] Controller[Controller] DB[(MySQL)] Queue[Queue Worker] AIcalls[AI Service Calls] Response[Response to Client] In --> Auth --> Validate --> Controller --> DB Controller -->|enqueue| Queue Controller -->|direct call| AIcalls AIcalls --> Response ``` Responsibilities: - Authentication and authorization (API tokens, OAuth, or guards configured in `config/auth.php`). - Centralized error handling and logging. - Exposes REST endpoints used by UI and third-party clients; routes live under `routes/`. - Job dispatching and scheduling; queue worker executes heavy pipelines. Where to look in repository: - `app/Http/Controllers/` — controllers and endpoints - `routes/api.php` — API routes and versioning - `jobs/` and `app/Jobs` — background job implementations - `docker/laravel.env` — example env values 2) ADMET inference (FastAPI) ```mermaid flowchart TD Req[POST /predict] Validate[SMILES Validation (RDKit)] Feat[Featurization / Graph builder] Models[MPNN Models (5 tasks)] Aggregate[Aggregate predictions] Return[JSON response] Req --> Validate --> Feat --> Models --> Aggregate --> Return ``` Responsibilities: - Load pre-trained MPNN models on startup (check `models/` inside service). - Validate SMILES strings with RDKit and sanitize input. - Support single and batch prediction endpoints; expose `/health` and `/docs`. - CPU-optimized inference (no GPU assumed by default) and async handling via Uvicorn. Where to look: - `ai_apps/ADMIT/admet_inference/` — service code, `README.md`, `Dockerfile`, `requirements.txt`. - Health and docs endpoints available at `http://:/health` and `/docs`. 3) Drug Repurposing (FastAPI) ```mermaid flowchart TD Req[POST /api/v1/screen] Targets[OpenTargets integration] Sequences[UniProt fetch] Drugs[Drug library (TDC / fallback)] Model[DeepPurpose MPNN-CNN] Results[Rank & postprocess] Return[JSON summary] Req --> Targets --> Sequences --> Drugs --> Model --> Results --> Return ``` Responsibilities: - Full screening pipeline: disease→targets→proteins→screening→results. - Integrates external APIs (OpenTargets, UniProt) and TDC for drug libraries. - Provides mock modes for offline testing (use env `USE_MOCK_MODEL` and `USE_MOCK_DRUGS`). Where to look: - `ai_apps/Drug Reporposing/` — service implementation, `docker/` folder, `requirements.txt`, `README.md` and helper scripts (`start.sh`, `start.bat`). 4) Chemical RAG (FAISS + LLM) ```mermaid flowchart TD Req[/search/full-rag] Validate[SMILES validation] FP[Morgan fingerprint / embedding] FAISS[FAISS-IVF index lookup] LLM[LLM explanation (optional)] Format[Result formatting] Return[JSON results] Req --> Validate --> FP --> FAISS --> LLM --> Format --> Return ``` Responsibilities: - High-performance similarity search for large compound libraries (1M+). - Persistent FAISS index stored on volume (`chemical-rag-data`). - Two endpoints: retrieval-only and full RAG (with LLM explanations); auto-detects and ingests compounds on first run. Where to look: - `ai_apps/chemical-rag-system/chemical-rag-system/` — engine, ingestion scripts, FAISS index code, `run_server.py`, and `README.md`. Environment variables & configuration locations --------------------------------------------- - Root compose: `docker-compose.yml` — service names, build contexts, ports, and env files. - Laravel env template: `docker/laravel.env` — application and DB defaults. - Each AI service: check `ai_apps//` for `requirements.txt`, `Dockerfile`, and service-specific config (e.g., `app/config.py`). Production deployment notes ------------------------- - Resource limits: `docker-compose.yml` contains `deploy.resources.limits` for AI services; tune these for production (memory, CPU). - Secrets: move sensitive env values into secret managers (Kubernetes Secrets, Vault) in production. - HTTPS: terminate TLS at a reverse proxy in front of `laravel` (Nginx/Load Balancer) and restrict internal-only exposure for AI services. Scaling considerations --------------------- - Horizontal scaling of AI services: deploy multiple replicas behind a load balancer. Ensure models are loaded on container start and center model size is within available RAM. - FAISS index: store on a shared volume or use a dedicated retrieval service with replicated indices. - Database: use managed RDS/MariaDB clusters or replicas for HA. Troubleshooting checkpoints -------------------------- - Service not healthy: `docker compose logs -f ` and `docker compose ps` to check ports and status. - Model load errors: inspect service logs, confirm model files under `models/` or configured model path. - FAISS ingestion slow: watch `chemical-rag` logs on first-run ingestion; ensure sufficient CPU and disk I/O. Appendix — quick visual references --------------------------------- - Root system diagram: see top of this file (Mermaid block). - Per-service diagrams: each service section above contains its own Mermaid block. Next steps I can implement for you ---------------------------------- 1. Generate PNG/SVG exports of these Mermaid diagrams and add them to the repo docs folder. 2. Standardize and replace `ai_apps/*/README.md` with a consistent template including: purpose, architecture diagram, setup (Docker + local), env vars, run commands, API endpoints, troubleshooting. 3. Create `docs/` folder and add `QUICK_START.md`, per-service `.env.example`, and the generated diagrams. Tell me which of the next steps you'd like me to do now (1, 2, 3), or if you want all of them performed.