AIGDM System

Offline Windows distribution for the AIGDM gestational diabetes mellitus clinical support system.

This README is written for the packaged release directory:

<extracted-aigdm_system-folder>

If you are using a copied release zip, treat the extracted aigdm_system folder as the application root. Run commands from that folder unless noted otherwise.

What Is Included

• Django application modules for maternal records, lab results, data imports, risk assessment, follow-ups, audit logs, dashboards, system configuration, and PKL model version management.
• Windows graphical installer: install-aigdm.bat.
• Command-line startup script: start-aigdm.ps1.
• Offline Python/Conda runtime archive: runtime\aigdm-system.zip.
• Optional pre-expanded runtime folder: .runtime\aigdm-system.
• Model registry directory model_files; PKL model artifacts are not bundled by default unless the package is built with -IncludeModels.
• Deployment scripts and reference docs under deploy and scripts.

The offline package is designed so the target machine does not need a separate Python or Conda installation when the embedded runtime is present.

Recommended Use

Use this package for Windows workstation, internal server, or acceptance-test deployment. For production use, deploy it on an internal network, use MySQL 8, configure access control at the network boundary, and validate the model and workflow with local clinical owners before use.

AIGDM is a clinical decision-support application. It does not replace physician review, local clinical policy, or regulatory validation.

System Requirements

• Windows 10/11 or Windows Server.
• PowerShell 5.1 or newer.
• MySQL 8 for production or shared use.
• Permission to write to the application folder and configured data folders.
• A browser that can access the configured host and port.

The embedded runtime is used automatically from runtime\aigdm-system.zip or .runtime\aigdm-system. If it is missing, the scripts fall back to an activated Conda environment, .conda\python.exe, conda run -n aigdm-system, or system python.

Package Layout

aigdm_system\
  install-aigdm.bat
  start-aigdm.ps1
  manage.py
  runtime\aigdm-system.zip
  .runtime\aigdm-system\
  accounts\
  aigdm\
  audit\
  common\
  dashboard\
  followups\
  integrations\
  labs\
  maternal_records\
  risk\
  system_config\
  model_files\
  scripts\
  static\
  templates\
  deploy\

Do not delete runtime, .runtime, static, or templates from a release folder. Keep model_files if present; in public packages it may contain only a README placeholder until a model is uploaded or copied on the target machine.

Before Installing

Create a MySQL database and user before running the installer.

Example:

CREATE DATABASE aigdm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'aigdm'@'%' IDENTIFIED BY 'replace-with-strong-password';
GRANT ALL PRIVILEGES ON aigdm.* TO 'aigdm'@'%';
FLUSH PRIVILEGES;

Keep the database password available. The installer writes the connection values to .env in the application root.

Install With The Windows Wizard

1. Open the release folder:

   <extracted-aigdm_system-folder>
   

2. Double-click:

   install-aigdm.bat
   

3. Fill in:

   • MySQL host, port, database name, user, and password.
   • Allowed hosts, for example 127.0.0.1,localhost,aigdm.local.
   • System administrator username and password.
   • Model, import, backup, and static file directories.
   • Startup host and port.

4. Click Test MySQL if you want to check database connectivity first.

5. Click Start installation.

The installer performs these steps:

• Resolves or expands the embedded runtime.
• Writes .env.
• Applies database migrations.
• Creates or updates the system administrator.
• Initializes roles, default permissions, rules, departments, and model metadata.
• Collects static files.
• Runs a deployment check report.
• Optionally starts the local service window.

The installer log is written to:

install-aigdm.log

Start The System

After installation, start from PowerShell:

cd <extracted-aigdm_system-folder>
.\start-aigdm.ps1

The default address is:

http://127.0.0.1:8001/

Use a different host or port when needed:

.\start-aigdm.ps1 -HostAddress 0.0.0.0 -Port 8010

For a local troubleshooting run that skips the strict deployment doctor:

.\start-aigdm.ps1 -SkipDoctor

Stop the development server with Ctrl+C in the PowerShell window.

Main URLs

Replace the host and port with your configured values.

Workspace:     http://127.0.0.1:8001/
Login:         http://127.0.0.1:8001/accounts/login/
Admin:         http://127.0.0.1:8001/admin/
API prefix:    http://127.0.0.1:8001/api/v1/

Configuration

The installer creates .env in the application root. Important values include:

DJANGO_SETTINGS_MODULE=aigdm.settings.production
AIGDM_DEBUG=0
AIGDM_SECRET_KEY=replace-with-local-random-secret
AIGDM_ALLOWED_HOSTS=127.0.0.1,localhost,aigdm.local

AIGDM_DB_ENGINE=mysql
AIGDM_DB_NAME=aigdm
AIGDM_DB_USER=aigdm
AIGDM_DB_PASSWORD=replace-with-strong-password
AIGDM_DB_HOST=127.0.0.1
AIGDM_DB_PORT=3306

AIGDM_MODEL_DIR=D:\aigdm\model_files
AIGDM_IMPORT_DIR=D:\aigdm\import_files
AIGDM_BACKUP_DIR=D:\aigdm\backups
AIGDM_STATIC_ROOT=D:\aigdm\staticfiles
AIGDM_MODEL_REGISTRY_TTL_SECONDS=5
AIGDM_MODEL_TIMEOUT_SECONDS=10

AIGDM_ADMIN_USERNAME=aigdm_admin

After changing .env, restart the service window.

Useful Maintenance Commands

Run these from the application root. Use the embedded runtime by calling start-aigdm.ps1, or call Python directly if you have an activated environment.

.\.runtime\aigdm-system\python.exe manage.py doctor
.\.runtime\aigdm-system\python.exe manage.py migrate
.\.runtime\aigdm-system\python.exe manage.py collectstatic --noinput
.\.runtime\aigdm-system\python.exe manage.py initialize_system --create-admin

If .runtime\aigdm-system has not been expanded yet, run the installer or .\start-aigdm.ps1 once first.

Model Files

Public source downloads and default installer packages do not include PKL model artifacts. This prevents local clinical model files from being uploaded to GitHub or public release archives.

To build a private internal package that includes model artifacts, explicitly opt in:

.\build-windows-installer-package.bat -FullOffline -IncludeModels

If the package does not include models, upload and validate a model from the system administration workflow, or place the model file on the target machine and register it with the management commands.

The default initial model version code used by the project is:

20250701_xgboost_ctgan55_tvae2

Expected model release path:

model_files\releases\20250701_xgboost_ctgan55_tvae2\model.pkl

For later model releases, place each version in its own folder under:

model_files\releases\<version_code>\

Do not overwrite an old model version in place. Validate and activate a new version through the system administration workflow or management commands.

Backups And Data

Back up at least:

• The MySQL database.
• The configured AIGDM_MODEL_DIR.
• The configured AIGDM_IMPORT_DIR.
• The configured AIGDM_BACKUP_DIR.
• The .env file, stored securely.

Do not commit or share .env, database dumps, patient data, imported source files, or model files containing protected data.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Troubleshooting

The installer cannot connect to MySQL

Check that MySQL is running and that the database, user, password, host, and port are correct. The MySQL user must have privileges on the target database.

Startup says .env is missing

Run install-aigdm.bat first, or create .env with the required values.

Startup fails during deployment doctor

Run:

.\.runtime\aigdm-system\python.exe manage.py doctor

Fix the reported database, directory, migration, model, or administrator issue, then start again.

The embedded runtime is invalid

Delete only:

.runtime\aigdm-system

Then run install-aigdm.bat or .\start-aigdm.ps1 again. The scripts will re-expand runtime\aigdm-system.zip.

Port is already in use

Start with another port:

.\start-aigdm.ps1 -Port 8010

Static files are missing

Run:

.\.runtime\aigdm-system\python.exe manage.py collectstatic --noinput

Then restart the service.

More Deployment Notes

See:

deploy\windows-installer-package.md
deploy\README-deploy.zh-CN.md
deploy\offline-package.md
deploy\backup-restore.md