Skip to content

README.md

Latest commit

 

History

History
153 lines (112 loc) · 5.6 KB

README.md

File metadata and controls

153 lines (112 loc) · 5.6 KB
Raw

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