ARCHITECTURE.md

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)

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)

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)

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://<host>:<port>/health and /docs.

3. Drug Repurposing (FastAPI)

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)

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/<service>/ 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 <service> 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.