1brahimmohamed/ASL-Parameter-GeneratorLight logoASL Parameter Generator Documentation

Folder Structure

Detailed explanation of the project folder structure and organization

Folder Structure

This document provides a comprehensive overview of the ASL Methods Section Generator project structure, explaining the purpose and organization of each directory and file.

Root Directory Structure

ASL-Methods-Generator/
├── package/                    # Python package (pyaslreport)
├── apps/                       # Application components
├── docs/                       # Documentation
├── docker-compose.yml          # Container orchestration
└── README.md                   # Project overview

Package Directory (package/)

The package/ directory contains the core Python package (pyaslreport) that provides the main functionality for data processing, validation, and report generation.

Package Structure

package/
├── src/
│   └── pyaslreport/        # Main package source code
├── tests/                  # Package unit tests
├── pyproject.toml          # Package configuration
├── requirements.txt        # Package dependencies
├── README.md               # Package documentation
├── LICENSE                 # MIT License
└── MANIFEST.in             # Package distribution files

Core Package Source (src/pyaslreport/)

Main Entry Points

src/pyaslreport/
├── __init__.py           # Package initialization
├── main.py               # Main package functions
└── cli/                  # Command-line interface
    ├── __init__.py
    └── generate_report.py

Key Files:

  • main.py: Contains the primary generate_report() function and BIDS metadata extraction
  • cli/generate_report.py: Command-line interface for the package

Modalities System

src/pyaslreport/modalities/
├── __init__.py
├── base_processor.py     # Base processor class
├── base_validator.py     # Base validator class
├── registry.py          # Modality registration system
├── asl/                 # ASL modality implementation
│   ├── __init__.py
│   ├── processor.py     # ASL data processor
│   ├── validator.py     # ASL validation logic
│   ├── report_generator.py # ASL report templates
│   ├── utils.py         # ASL-specific utilities
│   ├── constants.py     # ASL constants
│   └── validators/      # ASL validation rules
│       ├── __init__.py
│       ├── base_asl_validator.py
│       ├── boolean_validator.py
│       ├── consistency_validator.py
│       ├── json_validator.py
│       ├── number_array_validator.py
│       ├── number_or_number_array_validator.py
│       ├── number_validator.py
│       └── string_validator.py
└── testdsc/             # DSC modality (in development)
    ├── __init__.py
    ├── processor.py
    └── validator.py

Key Components:

  • base_processor.py: Abstract base class for all modality processors
  • registry.py: Dynamic modality registration system
  • asl/processor.py: Main ASL data processing logic
  • asl/validator.py: ASL parameter validation
  • asl/report_generator.py: ASL report template generation

Sequence Management

src/pyaslreport/sequences/
├── __init__.py
├── base_sequence.py     # Base sequence class
├── factory.py           # Sequence factory pattern
├── ge/                  # GE Healthcare sequences
│   ├── __init__.py
│   ├── ge_base.py      # GE base sequence
│   ├── asl/            # GE ASL sequences
│   │   ├── __init__.py
│   │   ├── ge_asl_base.py
│   │   ├── ge_basic_single_pld.py
│   │   └── ge_easl_multi_pld.py
│   └── dsc/           # GE DSC sequences
│       ├── __init__.py
│       └── ge_dsc_sequence.py # ( not implemented )
├── siemens/            # Siemens sequences ( not implemented )
│   ├── __init__.py
│   ├── siemens_base.py # Siemens base sequence ( not implemented )
│   ├── asl/            # Siemens ASL sequences ( not implemented )
│   │   ├── __init__.py
│   │   └── siemens_basic_single_pld.py
│   └── dsc/           # Siemens DSC sequences ( not implemented )
│       ├── __init__.py
│       └── siemens_dsc_sequence.py
└── philips/            # Philips sequences ( not implemented )
    ├── asl/
    └── dsc/

Key Components:

  • factory.py: Factory pattern for creating appropriate sequence objects
  • base_sequence.py: Abstract base class for all sequences
  • Vendor-specific implementations for GE, Siemens, and Philips

Input/Output System

src/pyaslreport/io/
├── __init__.py
├── readers/            # File reading utilities
│   ├── __init__.py
│   ├── file_reader.py  # Generic file reader
│   ├── nifti_reader.py # NIfTI file processing
│   └── yaml_reader.py  # YAML configuration reading
└── writers/            # Output generation
    ├── __init__.py
    ├── json_writer.py  # JSON report output
    ├── report_writer.py # Formatted report generation
    └── tsv_writer.py   # TSV file output

Core Configuration

src/pyaslreport/core/
├── __init__.py
├── config.py           # Configuration management
├── exceptions.py       # Custom exceptions
├── logging.py          # Logging configuration
└── config/            # Configuration files
    ├── allowed_file_types.yaml
    └── schemas/       # Validation schemas
        ├── consistency_schema.yaml
        ├── major_error_schema.yaml
        ├── recommended_condition_schema.yaml
        ├── recommended_validator_schema.yaml
        ├── required_condition_schema.yaml
        └── required_validator_schema.yaml

Utilities

src/pyaslreport/utils/
├── __init__.py
├── dicom_tags_utils.py    # DICOM tag utilities
├── general_utils.py       # General utility functions
├── math_utils.py          # Mathematical utilities
├── unit_conversion_utils.py # Unit conversion utilities
└── validation_utils.py    # Validation utilities

Enums and Types

src/pyaslreport/enums/
├── __init__.py
└── modaliy_enum.py    # Modality type enumerations

Converters

src/pyaslreport/converters/
├── __init__.py
└── dicom_to_nifti_converter.py # DICOM to NIfTI conversion

Applications Directory (apps/)

The apps/ directory contains the web application components: the frontend (Next.js) and backend (FastAPI).

Backend Application (apps/backend/)

apps/backend/
├── app/                # FastAPI application source
│   ├── __init__.py
│   ├── main.py        # FastAPI application entry point
│   ├── routers/       # API route handlers
│   │   ├── __init__.py
│   │   ├── data.py    # Data processing routes
│   │   └── reports.py # Report generation routes
│   └── utils/         # Backend utilities
│       └── report_template.py # PDF report templates
├── tests/             # Backend tests
│   ├── __init__.py
│   └── test_report.py
├── requirements.txt   # Python dependencies
├── Dockerfile         # Backend container
└── be_venv/          # Virtual environment (local)

Key Components:

  • main.py: FastAPI application setup with CORS middleware
  • routers/reports.py: Main API endpoints for report processing
  • utils/report_template.py: HTML templates for PDF generation

Frontend Application (apps/frontend/)

apps/frontend/
├── src/               # Source code
│   ├── app/          # Next.js app directory
│   │   ├── _home/    # Home page components
│   │   ├── _layout/  # Layout components
│   │   ├── convert/  # Conversion pages
│   │   ├── report/   # Report pages
│   │   │   ├── _components/
│   │   │   ├── errors/
│   │   │   ├── warnings/
│   │   ├── global-error.tsx
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/    # Reusable UI components
│   │   ├── general/   # General components
│   │   └── ui/        # UI components (shadcn/ui)
│   ├── enums/         # TypeScript enumerations
│   ├── hooks/         # Custom React hooks
│   ├── lib/           # Library utilities
│   ├── providers/     # React context providers
│   ├── services/      # API service functions
│   ├── types/         # TypeScript type definitions
│   └── utils/         # Utility functions
├── public/            # Static assets
├── package.json       # Node.js dependencies
├── tsconfig.json      # TypeScript configuration
├── next.config.ts     # Next.js configuration
├── postcss.config.mjs # PostCSS configuration
├── eslint.config.mjs  # ESLint configuration
├── components.json    # shadcn/ui configuration
├── Dockerfile         # Frontend container
└── README.md          # Frontend documentation

Key Components:

  • app/: Next.js 13+ app directory structure
  • components/ui/: shadcn/ui component library
  • providers/: React context for state management
  • services/: API communication layer
  • types/: TypeScript type definitions

Documentation Directory (docs/)

docs/
├── assets/            # Documentation assets
├── development/       # Developer documentation
├── user-guide/        # User documentation
├── index.mdx          # Main documentation page
├── next-steps.mdx     # Future development plans
└── docs.json          # Documentation configuration

Container Configuration

Docker Compose (docker-compose.yml)

services:
  frontend:
    build: ./apps/frontend
    ports: ["3000:3000"]
    environment:
      - NEXT_PUBLIC_API_BASE_URL=http://backend:8000/api
  
  backend:
    build: 
      context: .
      dockerfile: ./apps/backend/Dockerfile
    ports: ["8000:8000"]

Backend Dockerfile (apps/backend/Dockerfile)

  • Based on Python 3.11-slim
  • Installs the local package first
  • Sets up dependencies and environment
  • Exposes port 8000

Frontend Dockerfile (apps/frontend/Dockerfile)

  • Multi-stage build with Node.js 18
  • Optimized for production
  • Exposes port 3000

File Naming Conventions

Python Files

  • Modules: lowercase with underscores (asl_processor.py)
  • Classes: PascalCase (ASLProcessor)
  • Functions: lowercase with underscores (process_asl_data)
  • Constants: UPPERCASE with underscores (DURATION_OF_EACH_RFBLOCK)

TypeScript/JavaScript Files

  • Components: PascalCase (HomePage.tsx)
  • Hooks: camelCase with use prefix (use-mobile.ts)
  • Utilities: camelCase (countingUtils.ts)
  • Types: PascalCase (ReportResponseType.ts)

Configuration Files

  • Package configs: pyproject.toml, package.json
  • Build configs: Dockerfile, docker-compose.yml
  • Code quality: .eslintrc, tsconfig.json

Deployment Structure

Development

Local Development → Docker Compose → Local Services

Production

Production Server → Container Orchestration → Load Balancer → Services

Scalability Considerations

Horizontal Scaling

  • Stateless API design
  • Containerized services
  • Load balancer ready

Vertical Scaling

  • Modular package structure
  • Efficient memory usage
  • Optimized file processing
Markdown content contains an invalid component declaration called <Callout />. To remove this error, either declare the component locally or remove the declaration.
Edit this page on GitHub
Architecture
API Reference