diff --git a/docs/source/application_layers.rst b/docs/source/application_layers.rst new file mode 100644 index 0000000..2cdd898 --- /dev/null +++ b/docs/source/application_layers.rst @@ -0,0 +1,89 @@ +Application Layers +================== + +This project can be understood in two documentation levels: + +* **UI layer**: templates, static assets, and page-level interactions that users see. +* **Backend layer**: Django views, forms, models, routing, and risk computation logic. + +UI Layer +-------- + +The UI is server-rendered with Django templates and enhanced with JavaScript snippets embedded in template partials. + +Key entry points +~~~~~~~~~~~~~~~~ + +* `qmra/templates/layout.html` provides the shared shell (page frame) for most pages. +* `qmra/templates/index.html` is the public landing page. +* `qmra/risk_assessment/templates/assessment-configurator.html` is the main guided workflow for creating a risk assessment. +* `qmra/risk_assessment/templates/assessment-result.html` presents simulation outputs and charts. +* `qmra/user/templates/*.html` handles authentication and account-facing screens. + +UI building blocks +~~~~~~~~~~~~~~~~~~ + +* **Global styling** is defined in `qmra/static/css/styles.css`. +* **Images/icons** are served from `qmra/static/img/`. +* **Dynamic form behavior** is placed in template fragments such as: + + * `qmra/risk_assessment/templates/inflows-form-js.html` + * `qmra/risk_assessment/templates/treatments-form-js.html` + * `qmra/risk_assessment/templates/risk-assessment-form-js.html` + +Typical UI flow +~~~~~~~~~~~~~~~ + +1. User opens the configurator page. +2. User selects/creates inflows, treatments, and exposure settings. +3. User submits the form. +4. Backend computes Monte Carlo outcomes. +5. Results page renders plots and export options. + +Backend Layer +------------- + +The backend is a Django application split into project-level wiring and feature apps (`risk_assessment` and `user`). + +Project-level backend +~~~~~~~~~~~~~~~~~~~~~ + +* `qmra/settings.py` contains Django configuration. +* `qmra/urls.py` maps root URL patterns to app routes. +* `qmra/views.py` contains project-level views (e.g., landing page). +* `manage.py` is the command entrypoint for local operations. + +Risk assessment domain backend +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* `qmra/risk_assessment/models.py` stores persisted domain entities. +* `qmra/risk_assessment/qmra_models.py` defines QMRA reference data structures used by the simulation logic. +* `qmra/risk_assessment/forms.py` validates and structures UI submissions. +* `qmra/risk_assessment/views.py` implements the request/response workflow for configurator, results, and CRUD operations. +* `qmra/risk_assessment/risk.py` executes core risk calculations and simulation logic. +* `qmra/risk_assessment/plots.py` prepares data visualizations returned to templates. +* `qmra/risk_assessment/exports.py` handles export generation for assessment results. +* `qmra/risk_assessment/urls.py` exposes risk-assessment routes. + +User/account backend +~~~~~~~~~~~~~~~~~~~~ + +* `qmra/user/models.py` contains user-facing data models. +* `qmra/user/views.py` handles registration, login-related pages, and account actions. +* `qmra/user/urls.py` defines account URL patterns. + +Data bootstrap and operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* `qmra/management/commands/seed_default_db.py` loads default entities. +* `qmra/management/commands/collect_static_default_entities.py` snapshots configured defaults into static JSON. +* `qmra/management/commands/export_default.py` exports default data sets. +* `qmra/static/data/*.json` stores default inflow, pathogen, treatment, source, reference, and exposure datasets consumed by backend workflows. + +Request lifecycle (high-level) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. URL dispatch in `qmra/urls.py` or app `urls.py` selects a view. +2. View instantiates forms, loads defaults/database entities, and validates input. +3. Risk logic in `risk.py` and helper modules computes outputs. +4. View sends context to templates for HTML rendering (and optional exports). diff --git a/docs/source/index.rst b/docs/source/index.rst index cd3c1f9..804d29d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,6 +5,7 @@ Welcome to QMRA's documentation! :maxdepth: 2 :caption: Contents: + application_layers QMRA is a Django project which experiments with deploying state-of-the-art techniques for Quantitative Microbial Risk Assessment (QMRA).