How yasmeen-code/ailixir_backend works
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: Services Domain services · Jobs Queue jobs · Api API controllers · api.php API routes
Components 20
Laravel API
Central PHP orchestration layer
- API routes · Public API surface and endpoint dispatch
routes/api.php - Web routes · Browser-facing routes for docs and admin pages
routes/web.php - API controllers · Domain controllers for auth, science, chemistry, and jobs
app/Http/Controllers/Api - Request validation · Typed request validation and input contracts
app/Http/Requests - Domain services · Business logic, orchestration, and external integration clients
app/Services - Queue jobs · Async execution for docking, screening, conversion, and simulation
app/Jobs - Repositories · Specialized persistence and query boundaries
app/Repositories - API response · Shared response normalization and payload shaping
app/Traits/ApiResponseTrait.php - Domain models · Persistent entities for users, chemistry, jobs, and science content
app/Models
Python AI Services
Standalone model-serving and pipeline workloads
- ADMET service · ADMET model serving with per-property checkpoints
ai_apps/ADMIT/admet_inference - Repurposing service · Target lookup, library screening, and result processing pipeline
ai_apps/Drug Reporposing/app - MD simulation · Protein-ligand simulation orchestration and async task handling
ai_apps/Protein-Ligand-MD-Simulation/app - Scientific OS · Agent, memory, and orchestrator layer for scientific workflows
ai_apps/Scientific-Operating-System/app - Chemical RAG · Chemical retrieval, ingestion, and generation stack
ai_apps/chemical-rag-system/chemical-rag-system/app - Generation bundle · Bundled generator, affinity, and docking assets
ai_apps/generation
State & Storage
Database, jobs, and file assets
- Relational DB · Laravel-managed relational schema for auth, jobs, chemistry, and subscriptions
database/migrations - Files & assets · Uploaded files, generated outputs, docking fixtures, and public assets
storage
Ops & Verification
Containers, CI, and tests
- Test suites · PHP feature/unit tests and Python API regression tests
tests - Docs & CI · Scribe docs, diagrams, GitHub workflows, and release automation
.scribe - Containers · Dockerfiles, compose stacks, and service deployment entrypoints
Dockerfile
Connections 25
- 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