FindingModelForge

Tool set for creating finding models for defining the semantic labels for imaging findings.

FindingModelForge is a FastAPI web application exposing findingmodel functionality. The app uses GitHub OAuth for authentication, Jinja2 for templating, and provides a modern web interface with Tailwind CSS and Alpine.js.

Run

Prereqs

Requirements:

• uv: Install with:

  curl -LsSf https://astral.sh/uv/install.sh | sh

• Task: Install depends on system;

  MacOS:

  brew install gotask

  Windows:

  winget install Task.Task

• Docker

Build/Run Docker Image

task build
task run-container

Browse to localhost:8000 to access the web application.

Development Mode

For development with hot reload:

task dev

For development with CSS watching:

task dev-watch

Common development commands:

task setup          # Install deps + create .env + build assets
task test            # Run tests with coverage (70 tests, 71% router coverage)
task test-unit       # Fast unit tests only
task lint            # Lint and fix code issues
task format          # Format code
task check           # Quality checks (CI-friendly)
task build-frontend  # Build CSS and JS assets

Development Processes

Dev Tooling/CI

• Linting and formatting using ruff configured via a pyproject.toml file
• Type checking using mypy with strict mode
• Unit testing and coverage with pytest
• Use task for integration tasks (lint, format, type-check, test, build)
• Pre-commit hooks for automated code quality checks
• GitHub Actions for automatic checking on commit for formatting, linting, and passing tests
• Set up Dependabot to keep dependencies up to date

Deployment (eventually CD)

• Build any packages and create releases on GitHub; automate with GitHub actions as appropriate
• Build app container image with task and push to GitHub Container Registry
• Temporarily, manual deployment to Railway, with separate staging/ production environments.
• Later, move to continuous deployment with GitHub Actions

Code Standards

• Target Python version 3.12+
• Extensive type hinting throughout the codebase
• Environment variables for configuration using pydantic-settings
• Async/await patterns for I/O operations
• Comprehensive error handling and logging

Draft Management System

Complete draft lifecycle with autosave, resume, submit, and delete functionality:

• Auto-save on Step 4: Drafts automatically created/updated when editing attributes
• Unified draft pages: Single endpoint handles both edit and view modes via ?mode= parameter
• Session adoption: Automatic recovery of draft state when sessions are lost
• User isolation: One editable draft per (user_id, name) combination with secure ownership checks
• Action logging: Comprehensive audit trail for all draft operations
• Status management: draft → submitted → [future: under-review | added | declined]
• Smart resume: Entering the same finding name after submit shows final display view
• Redis integration: Cache layer available throughout with graceful degradation

UI Guidelines

• Flowbite components first; keep to their HTML structure and data-attributes.
• Alpine.js for local state and interactivity (x-data, x-model, x-show, computed methods). Avoid custom vanilla JS.
• Use Jinja2 macros in templates/macros where possible (see flowbite_components.html, layout_components.html, json_accordion.html).
• HTMX is used for server-driven fragments in multi-step forms.

Preferred Libraries

• Data

  • pydantic for data model definitions:
    • Drives APIs
    • Drives database models via ODM
    • Drives web UI
    • Exports JSON schemas
    • Used for structured data extraction
  • motor - Asynchronous MongoDB operations and queries

• Web

  • fastapi - REST API development and endpoint handling
  • uvicorn - ASGI server implementation for application hosting
  • jinja2 - Server-side templating engine with template inheritance
  • redis - In-memory caching layer for performance optimization

• Frontend

  • tailwindcss - Utility-first CSS framework with dark mode support
  • alpinejs - Lightweight JavaScript framework for interactivity
  • flowbite - Pre-built UI components with data-attribute patterns
  • vite - Modern frontend build system with hot reload
  • htmx - Server-driven interactivity for multi-step flows

• Logging

  • loguru - Application logging and debugging infrastructure

• Authentication & Security

  • pyjwt - JWT token generation and validation
  • httpx - HTTP client for OAuth integration