# yasmeen-code/ailixir_backend architecture

> Architecture diagram of the GitHub repository yasmeen-code/ailixir_backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yasmeen-code/ailixir_backend
- Repository: https://github.com/yasmeen-code/ailixir_backend

## Overview

1. **Overall shape**
   - This is a **monorepo** centered on a **Laravel/PHP API** that orchestrates scientific and AI-driven workflows.
   - The main app is in the root `app/`, `routes/`, `database/`, `resources/`, and `public/` directories.
   - A second major axis is a set of **standalone Python AI services** under `ai_apps/`, each packaged and deployed separately.

2. **Primary runtime boundary: Laravel API**
   - The Laravel app exposes the public API through `routes/api.php` and `app/Http/Controllers/Api/*`.
   - It also serves a small web/admin/documentation layer via `routes/web.php` and Blade views in `resources/views/`.
   - The API is the central coordinator: it handles authentication, user/profile features, content endpoints, and science/AI jobs.

3. **Application layering in the PHP backend**
   - Request validation is separated into `app/Http/Requests/*`.
   - Controllers delegate business logic to `app/Services/*` and some domain-specific repositories in `app/Repositories/*`.
   - API responses are normalized through `app/Traits/ApiResponseTrait.php` and resource classes in `app/Http/Resources/*`.
   - This gives a clear flow of **HTTP request → validation → controller → service/repository → model/database → response**.

4. **Core domain modules exposed by the API**
   - The backend is organized around several domains:
     - **Auth and user management**: login, registration, password reset, email verification, OTP, profile.
     - **Scientific content**: awards, scientists, news, saved articles.
     - **Chemistry and drug discovery**: chemical search, SMILES conversion, docking, screening, ADMET, molecular dynamics, generation.
     - **Subscriptions and job tracking**: AI jobs, docking jobs, simulations, screening results, chemistry threads/analyses.
   - These domains are reflected in both controllers and database models.

5. **Async/work-queue architecture**
   - Heavy operations are not handled synchronously in controllers; they are pushed into Laravel jobs in `app/Jobs/*`.
   - Examples include docking, molecular dynamics simulation, screening, CSV processing, SMILES conversion, and OTP delivery.
   - The database schema includes dedicated job/result tables such as `ai_jobs`, `docking_jobs`, `simulations`, `screening_results`, `chemical_search_jobs`, and `chemistry_csv_jobs`.
   - This indicates a **request/submit → queued processing → status/result retrieval** pattern.

6. **AI service integration boundary**
   - The Laravel app does not appear to run the scientific models itself; it integrates with external AI services through `app/Services/AiServiceClient.php` and `ChemistryApiService.php`.
   - The `ai_apps/` tree contains multiple independent services that likely back these endpoints:
     - **ADMET inference**
     - **Drug repurposing**
     - **Protein-ligand MD simulation**
     - **Chemical RAG system**
     - **Scientific operating system / agent layer**
     - **Generation/docking bundle**
   - Architecturally, this is a **PHP orchestration layer** calling into **Python model-serving workloads** over HTTP/container boundaries.

7. **Notable AI subservices**
   - **ADMET**: a Python service with model checkpoints for absorption, distribution, excretion, metabolism, and toxicity.
   - **Drug repurposing**: a pipeline-oriented Python app with target lookup, protein sequences, PDB structures, drug library screening, and result processing.
   - **Protein-Ligand-MD-Simulation**: includes a Celery app, pipeline orchestration, and job/result utilities, signaling asynchronous compute-heavy simulation handling.
   - **Generation**: contains model bundles, docking maps, and affinity/generator assets, suggesting a specialized generation + docking inference stack.
   - These are separable service boundaries, not just library code.

8. **Data persistence and file storage**
   - The system uses a relational database managed by Laravel migrations and models.
   - The schema is broad and domain-specific, covering authentication, scientists/awards/news, chemistry threads, AI jobs, docking jobs, simulations, and subscriptions.
   - File storage is also part of the design: `storage/`, `public/`, `resources/docking/`, and bundled assets under `ai_apps/*/models` and `bundle/`.
   - Some features rely on uploaded/generated files such as CSVs, structure files, docking fixtures, and model artifacts.

9. **Security, identity, and notifications**
   - Authentication includes Laravel Sanctum, email verification, password reset, OTP, and role-based access.
   - Middleware such as `CheckJobOwnership`, `Subscribed`, and `EnsureChemistryApiAvailable` enforce access and dependency readiness.
   - Notifications and queued messages are used for user-facing events like OTP and CSV completion.

10. **API documentation and contract generation**
   - The repository uses **Scribe** for API documentation; the `.scribe/` directory and `resources/views/scribe/` indicate generated endpoint docs.
   - There are also dedicated documentation pages in `resources/views/api-docs.blade.php` and `resources/views/api-endpoints.blade.php`.
   - This suggests the API contract is treated as a first-class artifact, likely important for external clients and for the separate test suite.

11. **Deployment and runtime topology**
   - The project is containerized with multiple Docker setups: root `Dockerfile`, `docker-compose.yml`, GPU variants, and service-specific Dockerfiles under `ai_apps/`.
   - Nginx/PHP-FPM is the primary web runtime for the Laravel app.
   - Some AI services have their own compose files and entrypoints, indicating they are deployed as **independent containers or services** rather than embedded modules.
   - Environment files (`.env.example`, `.env.docker`, `.env.hf`) and Hugging Face-related workflows show the system supports multiple deployment targets.

12. **Testing and verification**
   - There are **PHP tests** under `tests/` for the Laravel app and **Python API tests** at the repo root for external API validation.
   - The top-level README also frames the repo as an **AILIXIR API test suite**, which suggests the repository is used both as product code and as contract/regression coverage around that API.
   - CI workflows in `.github/workflows/` run API tests, integration tests, Hugging Face syncs, and model publishing.

13. **How to draw the architecture**
   - Place the **Laravel API** in the center as the orchestrator.
   - Draw **clients** on the left/top: API consumers, web views, and test suites.
   - Draw **database/storage** below: relational DB, uploaded/generated files, and public assets.
   - Draw **async workers/queue** beside the API for jobs.
   - Draw **external AI microservices** as separate boxes under `ai_apps/`, connected from Laravel through service clients and job execution paths.
   - Add **docs/CI/CD** as supporting, non-runtime subsystems around the main application.

Main entry points: [`app/Services`](https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Services) (Domain services), [`app/Jobs`](https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Jobs) (Queue jobs), [`app/Http/Controllers/Api`](https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Http/Controllers/Api) (API controllers), [`routes/api.php`](https://github.com/yasmeen-code/ailixir_backend/blob/main/routes/api.php) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients & Docs"]
end

subgraph group_php["Laravel API"]
  node_api_routes["API routes<br/>Laravel HTTP<br/>[api.php]"]
  node_web_routes["Web routes<br/>Laravel HTTP<br/>[web.php]"]
  node_api_controllers["API controllers<br/>HTTP controllers"]
  node_form_requests["Request validation<br/>Laravel requests"]
  node_domain_services["Domain services<br/>application services"]
  node_job_workers["Queue jobs<br/>background jobs"]
  node_repositories["Repositories<br/>data access"]
  node_api_response["API response<br/>response trait"]
  node_models[("Domain models<br/>Eloquent models")]
end

subgraph group_ai["Python AI Services"]
  node_admet_service["ADMET service<br/>Python inference"]
  node_repurposing_service["Repurposing service<br/>Python pipeline"]
  node_md_service["MD simulation<br/>Celery pipeline"]
  node_sos_service["Scientific OS<br/>agent service"]
  node_rag_service["Chemical RAG<br/>RAG service"]
  node_generation_bundle["Generation bundle<br/>generation+docking"]
end

subgraph group_data["State & Storage"]
  node_laravel_db[("Relational DB<br/>migrations/schema")]
  node_file_assets["Files & assets<br/>storage/assets"]
end

subgraph group_ops["Ops & Verification"]
  node_tests["Test suites<br/>verification"]
  node_docs_ci["Docs & CI<br/>docs+automation<br/>[.scribe]"]
  node_deployment["Containers<br/>runtime packaging"]
end

node_api_routes -->|"dispatches"| node_api_controllers
node_web_routes -->|"shares logic"| node_api_controllers
node_api_controllers -->|"validates"| node_form_requests
node_api_controllers -->|"delegates"| node_domain_services
node_domain_services -->|"queries"| node_repositories
node_domain_services -->|"reads/writes"| node_models
node_domain_services -->|"formats"| node_api_response
node_repositories -->|"persists"| node_laravel_db
node_models -->|"maps to"| node_laravel_db
node_job_workers -->|"updates status"| node_laravel_db
node_job_workers -->|"reads/writes"| node_file_assets
node_job_workers -->|"calls"| node_admet_service
node_job_workers -->|"calls"| node_repurposing_service
node_job_workers -->|"calls"| node_md_service
node_job_workers -->|"calls"| node_generation_bundle
node_domain_services -->|"integrates"| node_admet_service
node_domain_services -->|"integrates"| node_rag_service
node_domain_services -->|"integrates"| node_sos_service
node_domain_services -->|"integrates"| node_generation_bundle
node_tests -->|"verifies"| node_api_routes
node_tests -->|"verifies"| node_admet_service
node_docs_ci -->|"documents"| node_api_routes
node_docs_ci -->|"builds"| node_deployment
node_deployment -->|"runs"| node_api_routes
node_deployment -->|"runs"| node_admet_service

click node_api_routes "https://github.com/yasmeen-code/ailixir_backend/blob/main/routes/api.php"
click node_web_routes "https://github.com/yasmeen-code/ailixir_backend/blob/main/routes/web.php"
click node_api_controllers "https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Http/Controllers/Api"
click node_form_requests "https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Http/Requests"
click node_domain_services "https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Services"
click node_job_workers "https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Jobs"
click node_repositories "https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Repositories"
click node_api_response "https://github.com/yasmeen-code/ailixir_backend/blob/main/app/Traits/ApiResponseTrait.php"
click node_models "https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Models"
click node_laravel_db "https://github.com/yasmeen-code/ailixir_backend/tree/main/database/migrations"
click node_file_assets "https://github.com/yasmeen-code/ailixir_backend/tree/main/storage"
click node_admet_service "https://github.com/yasmeen-code/ailixir_backend/tree/main/ai_apps/ADMIT/admet_inference"
click node_repurposing_service "https://github.com/yasmeen-code/ailixir_backend/tree/main/ai_apps/Drug Reporposing/app"
click node_md_service "https://github.com/yasmeen-code/ailixir_backend/tree/main/ai_apps/Protein-Ligand-MD-Simulation/app"
click node_sos_service "https://github.com/yasmeen-code/ailixir_backend/tree/main/ai_apps/Scientific-Operating-System/app"
click node_rag_service "https://github.com/yasmeen-code/ailixir_backend/tree/main/ai_apps/chemical-rag-system/chemical-rag-system/app"
click node_generation_bundle "https://github.com/yasmeen-code/ailixir_backend/tree/main/ai_apps/generation"
click node_tests "https://github.com/yasmeen-code/ailixir_backend/tree/main/tests"
click node_docs_ci "https://github.com/yasmeen-code/ailixir_backend/blob/main/.scribe"
click node_deployment "https://github.com/yasmeen-code/ailixir_backend/tree/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_routes,node_web_routes,node_api_controllers,node_form_requests,node_domain_services,node_job_workers,node_repositories,node_api_response,node_models toneAmber
class node_admet_service,node_repurposing_service,node_md_service,node_sos_service,node_rag_service,node_generation_bundle toneMint
class node_laravel_db,node_file_assets toneRose
class node_tests,node_docs_ci,node_deployment toneIndigo
```

## Components

### Laravel API

Central PHP orchestration layer

- [API routes](https://github.com/yasmeen-code/ailixir_backend/blob/main/routes/api.php): Laravel HTTP · Public API surface and endpoint dispatch · `routes/api.php`
- [Web routes](https://github.com/yasmeen-code/ailixir_backend/blob/main/routes/web.php): Laravel HTTP · Browser-facing routes for docs and admin pages · `routes/web.php`
- [API controllers](https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Http/Controllers/Api): HTTP controllers · Domain controllers for auth, science, chemistry, and jobs · `app/Http/Controllers/Api`
- [Request validation](https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Http/Requests): Laravel requests · Typed request validation and input contracts · `app/Http/Requests`
- [Domain services](https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Services): application services · Business logic, orchestration, and external integration clients · `app/Services`
- [Queue jobs](https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Jobs): background jobs · Async execution for docking, screening, conversion, and simulation · `app/Jobs`
- [Repositories](https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Repositories): data access · Specialized persistence and query boundaries · `app/Repositories`
- [API response](https://github.com/yasmeen-code/ailixir_backend/blob/main/app/Traits/ApiResponseTrait.php): response trait · Shared response normalization and payload shaping · `app/Traits/ApiResponseTrait.php`
- [Domain models](https://github.com/yasmeen-code/ailixir_backend/tree/main/app/Models): Eloquent models · Persistent entities for users, chemistry, jobs, and science content · `app/Models`

### Python AI Services

Standalone model-serving and pipeline workloads

- [ADMET service](https://github.com/yasmeen-code/ailixir_backend/tree/main/ai_apps/ADMIT/admet_inference): Python inference · ADMET model serving with per-property checkpoints · `ai_apps/ADMIT/admet_inference`
- [Repurposing service](https://github.com/yasmeen-code/ailixir_backend/tree/HEAD/ai_apps/Drug%20Reporposing/app): Python pipeline · Target lookup, library screening, and result processing pipeline · `ai_apps/Drug Reporposing/app`
- [MD simulation](https://github.com/yasmeen-code/ailixir_backend/tree/main/ai_apps/Protein-Ligand-MD-Simulation/app): Celery pipeline · Protein-ligand simulation orchestration and async task handling · `ai_apps/Protein-Ligand-MD-Simulation/app`
- [Scientific OS](https://github.com/yasmeen-code/ailixir_backend/tree/main/ai_apps/Scientific-Operating-System/app): agent service · Agent, memory, and orchestrator layer for scientific workflows · `ai_apps/Scientific-Operating-System/app`
- [Chemical RAG](https://github.com/yasmeen-code/ailixir_backend/tree/main/ai_apps/chemical-rag-system/chemical-rag-system/app): RAG service · Chemical retrieval, ingestion, and generation stack · `ai_apps/chemical-rag-system/chemical-rag-system/app`
- [Generation bundle](https://github.com/yasmeen-code/ailixir_backend/tree/main/ai_apps/generation): generation+docking · Bundled generator, affinity, and docking assets · `ai_apps/generation`

### State & Storage

Database, jobs, and file assets

- [Relational DB](https://github.com/yasmeen-code/ailixir_backend/tree/main/database/migrations): migrations/schema · Laravel-managed relational schema for auth, jobs, chemistry, and subscriptions · `database/migrations`
- [Files & assets](https://github.com/yasmeen-code/ailixir_backend/tree/main/storage): storage/assets · Uploaded files, generated outputs, docking fixtures, and public assets · `storage`

### Ops & Verification

Containers, CI, and tests

- [Test suites](https://github.com/yasmeen-code/ailixir_backend/tree/main/tests): verification · PHP feature/unit tests and Python API regression tests · `tests`
- [Docs & CI](https://github.com/yasmeen-code/ailixir_backend/blob/main/.scribe): docs+automation · Scribe docs, diagrams, GitHub workflows, and release automation · `.scribe`
- [Containers](https://github.com/yasmeen-code/ailixir_backend/tree/main/Dockerfile): runtime packaging · Dockerfiles, compose stacks, and service deployment entrypoints · `Dockerfile`

## Connections

- API routes → API controllers: dispatches · Routes map requests to domain controllers
- Web routes → API controllers: shares logic · Web pages reuse application controllers and services
- API controllers → Request validation: validates · Controllers consume typed request objects
- API controllers → Domain services: delegates · Controllers push business logic into services
- Domain services → Repositories: queries · Services use repositories for specialized persistence
- Domain services → Domain models: reads/writes · Services operate on Eloquent domain entities
- Domain services → API response: formats · Responses are normalized through shared trait helpers
- Repositories → Relational DB: persists · Repositories ultimately read and write relational state
- Domain models → Relational DB: maps to · Domain models are backed by the database schema
- Queue jobs → Relational DB: updates status · Queued jobs track progress and results in job tables
- Queue jobs → Files & assets: reads/writes · Jobs process uploaded inputs and generated artifacts
- Queue jobs → ADMET service: calls · Async and service-backed ADMET inference requests
- Queue jobs → Repurposing service: calls · Screening and repurposing workloads can be offloaded externally
- Queue jobs → MD simulation: calls · Molecular dynamics execution delegates to simulation service
- Queue jobs → Generation bundle: calls · Docking and generation workflows use bundled inference assets
- Domain services → ADMET service: integrates · PHP orchestration layer wraps external AI inference endpoints
- Domain services → Chemical RAG: integrates · Chemical search and retrieval flows use the RAG service
- Domain services → Scientific OS: integrates · Agentic scientific workflows are delegated to the operating system service
- Domain services → Generation bundle: integrates · Generation and docking APIs connect to the bundled stack
- Test suites → API routes: verifies · Feature and integration tests exercise the API contract
- Test suites → ADMET service: verifies · Python tests cover external AI service behavior
- Docs & CI → API routes: documents · Generated docs are derived from endpoint definitions
- Docs & CI → Containers: builds · Workflows build and publish containers and model artifacts
- Containers → API routes: runs · Laravel runtime is containerized behind web services
- Containers → ADMET service: runs · AI subsystems are deployed as independent containers