Developer Documentation

Key Locations

• Backend Source: app.py & backend/
• Frontend Source: static/ts/
• Frontend Template: static/html/

Frontend Development Workflow

1. Make changes to the TypeScript files in static/ts/.
2. Compile to JavaScript: You must compile the TypeScript to JavaScript for the browser to run it.

   pnpm run build        # One-time build (uses SWC for speed)
   pnpm run build:watch  # Watch for changes (uses SWC)

3. Run the backend (see Usage section) and refresh your browser.

Backend Development Workflow

1. Add/Modify Logic:
   • Create new modules in backend/ for organized logic (e.g., new file parsers, simulation controllers).
   • Import them in app.py.
2. Add Endpoints:
   • Define new routes in app.py using @app.route.
3. Honker Queue:
   • The /run endpoint uses honker to queue jobs. Background workers process these and update SQLite. Logs are streamed live via honker.stream().
4. Hot Reload / Debug Mode:
   • To enable the Flask reloader and automatic template refreshing for the frontend, run with the FLASK_DEBUG environment variable set to 1:

     $env:FLASK_DEBUG="1"; uv run python -m app

   • When enabled, the server will automatically restart when you modify Python files or the static/html/foamflask_frontend.html template.

Tech Stack & Frameworks

This project is built with robustness and simplicity in mind, avoiding heavy frontend frameworks in favor of a clean, performant architecture.

• Backend:

  • Python 3.13+: Core logic managed by uv.
  • Flask: Lightweight WSGI web application framework.
  • Docker SDK (docker-py): For programmatic control of Docker containers.
  • PyVista / VTK: For mesh processing and isosurface generation.
  • Custom Parsers: Dedicated Python parsers (realtime_plots.py) for reading both uniform and nonuniform OpenFOAM fields.

• Frontend:

  • TypeScript / SWC: For type-safe code and ultra-fast compilation (using SWC).
  • Vanilla DOM API: No React/Vue/Angular. Direct DOM manipulation for maximum performance.
  • TailwindCSS: Utility-first CSS framework for styling.
  • Plotly.js: For responsive, interactive charts (using data served by Flask endpoints).

• Architecture:

  • RESTful API for client-server communication.
  • Stateless Backend: The server does not maintain session state; state is managed by the client or persisted to disk.

Project Structure

FOAMFlask/
├── app.py # Main Flask application
├── case_config.json # Stores the last used CASE_ROOT
├── package.json # Node.js dependencies and build scripts
├── copy-built-js.mjs # Custom build script
├── static/
│ ├── html/
│ │ └── foamflask_frontend.html # HTML template
│ ├── ts/
│ │ └── foamflask_frontend.ts # TypeScript source code
│ ├── js/
│ │ ├── foamflask_frontend.js # Compiled JavaScript (for browser)
│ │ └── frontend/
│ │     └── isosurface.js # PyVista integration
│ ├── js-build/
│ │ └── foamflask_frontend.js # TypeScript compiler output
├── backend/
│ ├── geometry/
│ │ └── manager.py # Geometry management utilities
│ ├── mesh/
│ │ └── mesher.py # Mesh generation utilities
│ ├── plots/
│ │ └── realtime_plots.py # Real-time plotting backend
│ ├── post/
│ │ └── isosurface.py # Post-processing utilities
│ ├── verification/
│ │ └── verify_changes.py # Verification utilities
├── test/
│ ├── check_coverage.py # Code coverage analysis script
│ ├── check_docstrings.py # Docstring coverage checker
│ ├── docker_test.py # Docker functionality tests
│ ├── pyvista_test.py # PyVista integration tests
│ ├── foamlib_test.py # FOAM library tests
│ └── bike.vtp # Test VTK file
├── docs/ # Generated documentation
├── environments/ # Python virtual environments
└── README.md # This file

Testing

FOAMFlask includes a comprehensive test suite using pytest. The test suite includes unit tests, integration tests, and end-to-end tests for the application's core functionality.

Running Tests

1. Install test dependencies (if not already installed):

   uv sync

2. Run all tests with coverage:

   # Run all tests with coverage
   uv run pytest --cov=app --cov=backend --cov-report=term-missing --cov-report=html

3. Run specific test files or individual tests:

   # Run a specific test file
   uv run pytest test/test_app.py -v
   
   # Run a specific test function
   uv run pytest test/test_app.py::test_index_route -v

4. Run tests in parallel (faster execution):

   uv run pytest -n auto --cov=app --cov=backend

Test Coverage

To check test coverage and generate reports:

# Generate HTML coverage report (recommended)
uv run pytest --cov=app --cov=backend --cov-report=html

# View coverage in terminal
uv run pytest --cov=app --cov=backend --cov-report=term-missing

# Generate XML report (for CI/CD integration)
uv run pytest --cov=app --cov=backend --cov-report=xml

Coverage Reports:

• HTML report will be generated in the htmlcov directory
• Open htmlcov/index.html in your browser to view the detailed coverage report
• The terminal report shows which lines are missing coverage

Test Structure

test/
├── conftest.py        # Test fixtures and configuration
├── test_app.py        # Main application tests
└── test_security.py   # Security-related tests

Writing New Tests

1. Create a new test file following the naming convention test_*.py
2. Use pytest fixtures from conftest.py when available
3. Follow the existing test patterns for consistency
4. Include docstrings explaining what each test verifies

Test Coverage Commands Reference

# Run all tests with coverage
uv run pytest --cov=app --cov=backend

# Run tests without coverage
uv run pytest

# Run tests with detailed output
uv run pytest -v

# Run tests and stop after first failure
uv run pytest -x

# Run tests and show output from print statements
uv run pytest -s

# Run tests matching a specific pattern
uv run pytest -k "test_name_pattern"

---

For users who want to contribute or fork the project.

Project Architecture: Explain the folder structure (Flask backend, static/ HTML/JS frontend).

API Endpoints: A brief overview of the Flask routes that serve the plot data and execute commands.

Generating Docs: The pdoc commands currently at the bottom of your wiki for generating Python HTML/Markdown documentation.

Building/Extending: How to add new OpenFOAM command buttons or new plot types.