Noumaris Internal Docs

Appearance

Package Decisions ​

Comprehensive evaluation of all major packages and dependencies used in Noumaris.

Overview ​

This document covers package selection rationale, alternatives considered, health metrics, and ongoing evaluation criteria. For high-level architectural decisions, see ADR index.

Evaluation Criteria ​

All packages are assessed on:

  • Maturity: Active maintenance, release cadence, community size
  • Security: CVE history, security practices, audit status
  • Performance: Benchmarks, production usage, scalability
  • Cost: Licensing, usage-based pricing, maintenance burden
  • Alternatives: Why not competitors?

Backend Stack ​

FastAPI ​

Status: ✅ Adopted | Category: Web Framework | Health: 🟢 Excellent

Why FastAPI?

  • Async/await support for WebSocket and I/O operations
  • Automatic OpenAPI documentation (/docs)
  • Type safety with Pydantic validation
  • 3-4x faster than Django for async workloads
  • Small footprint, minimal dependencies

Metrics:

  • Version: 0.104+
  • License: MIT
  • GitHub Stars: 70k+
  • Downloads: 10M+/month
  • Maintenance: ✅ Active (weekly releases)

Alternatives Considered:

FrameworkProsConsVerdict
DjangoMature, batteries-included ORM, admin panelSync-first, slower for async, heavyweight❌ Too heavy for API-only service
FlaskLightweight, simpleNo async, manual validation, no auto docs❌ Lacks modern features
TornadoAsync supportSmaller community, less mature ecosystem❌ Less developer-friendly

Cost: Free (open source)

See Also: ADR-005: FastAPI vs Django

SQLAlchemy ​

Status: ✅ Adopted | Category: ORM | Health: 🟢 Excellent

Why SQLAlchemy?

  • Industry standard Python ORM
  • Excellent PostgreSQL support (JSON, arrays)
  • Works seamlessly with Alembic for migrations
  • Flexible: Core (SQL builder) + ORM layers
  • Strong type support

Metrics:

  • Version: 2.0+
  • License: MIT
  • Downloads: 50M+/month
  • Maintenance: ✅ Active

Alternatives:

ORMProsConsVerdict
Django ORMSimple, integratedTied to Django, less flexible❌ Not using Django
Tortoise ORMAsync-nativeSmaller community, less mature❌ Too new, limited docs
PeeweeLightweightLimited features❌ Too simple for complex queries

Cost: Free

Alembic ​

Status: ✅ Adopted | Category: Database Migrations | Health: 🟢 Excellent

Why Alembic?

  • Built by SQLAlchemy author
  • Auto-generates migrations from model changes
  • Downgrade support for rollbacks
  • Handles complex schema changes

Alternatives:

  • Django migrations (requires Django)
  • Flyway (Java-based, overkill)
  • Manual SQL scripts (error-prone)

Cost: Free

Pydantic ​

Status: ✅ Adopted | Category: Validation | Health: 🟢 Excellent

Why Pydantic?

  • Runtime type validation
  • Automatic JSON serialization
  • FastAPI integration (request/response validation)
  • Prevents injection attacks via strict typing

Metrics:

  • Version: 2.0+
  • License: MIT
  • Downloads: 50M+/month

Alternatives:

  • Marshmallow (less performant)
  • dataclasses (no validation)

Cost: Free

External Services ​

Keycloak ​

Status: ✅ Adopted | Category: Authentication | Health: 🟢 Excellent

Why Keycloak?

  • Self-hosted (HIPAA compliance, no data sent to 3rd party)
  • No per-user pricing ($0 vs $300/month for Auth0)
  • Open source, battle-tested
  • JWT, OAuth2, OIDC support
  • Terraform configurable

Metrics:

  • Version: 25.0+
  • License: Apache 2.0
  • Deployment: Google Cloud Run (containerized)
  • Cost: $15-20/month (Cloud Run hosting only)

Alternatives:

ServicePricingProsConsVerdict
Auth0$300/month (1000 users)Managed, excellent UXExpensive, data in 3rd party❌ Too expensive
Supabase AuthFree tier, $25/month proPostgres-based, simpleLimited enterprise features❌ Less mature
AWS Cognito$0.0055/MAUCheap, scalableComplex setup, vendor lock-in❌ Poor DX

Cost Savings: $300/month vs Auth0 = $3,600/year saved

See Also: ADR-001: Keycloak vs Auth0

Anthropic Claude ​

Status: ✅ Adopted | Category: LLM | Health: 🟢 Excellent

Why Claude?

  • 200k context window (entire patient history + template)
  • Strong medical reasoning capabilities
  • Lower cost than GPT-4 for equivalent quality
  • Canadian data residency option
  • JSON mode for structured output

Metrics:

  • Model: Claude 3.5 Sonnet
  • Pricing: $3/million input tokens, $15/million output
  • Typical note: ~$0.02-0.05 per generation
  • Monthly usage: ~$50-100 (1000-2000 notes)

Alternatives:

LLMProsConsVerdict
GPT-4Excellent quality128k context, $30/1M output (2x cost)❌ More expensive
Gemini ProFree tier, cheapLess consistent, worse medical reasoning❌ Quality concerns
Self-hosted LlamaNo API costsRequires GPU ($500+/month), latency, quality❌ Not cost-effective at scale

Cost Projection:

  • Current (100 notes/month): ~$5-10
  • Target (2000 notes/month): ~$100-150

Deepgram ​

Status: ✅ Adopted | Category: Speech-to-Text | Health: 🟢 Excellent

Why Deepgram?

  • Real-time WebSocket transcription
  • Medical vocabulary support
  • Speaker diarization (patient vs clinician)
  • Lower latency than OpenAI Whisper API
  • Competitive pricing

Metrics:

  • Pricing: $0.0125/minute pre-recorded, $0.0150/minute streaming
  • Typical encounter: 10-20 minutes = $0.15-0.30
  • Monthly (500 encounters): ~$75-150

Alternatives:

ServiceProsConsVerdict
OpenAI WhisperHigh accuracy, self-hostableNo real-time streaming API, slower❌ No WebSocket support
AssemblyAIGood featuresSimilar pricing, less proven🟡 Viable alternative
Google Speech-to-TextCheap, accuratePoor medical vocabulary❌ Not specialized

Cost: ~$75-150/month (production estimate)

Frontend Stack ​

React 18 ​

Status: ✅ Adopted | Category: UI Framework | Health: 🟢 Excellent

Why React?

  • Largest ecosystem (libraries, developers, resources)
  • Concurrent rendering for better UX
  • Server Components (future migration path)
  • Hiring advantage (most popular framework)

Alternatives:

  • Vue 3 (smaller ecosystem)
  • Angular (too heavyweight)
  • Svelte (too new, smaller community)

See Also: ADR-006: React vs Next.js

Vite ​

Status: ✅ Adopted | Category: Build Tool | Health: 🟢 Excellent

Why Vite?

  • 100x faster HMR than Webpack/CRA
  • Native ES modules
  • Instant server start
  • Optimized production builds (Rollup)

Metrics:

  • HMR: <50ms (vs 5s+ with Webpack)
  • Build time: ~10s (vs 60s+ with CRA)

Alternatives:

  • Webpack (slow HMR)
  • Create React App (deprecated)
  • Turbopack (too new, Next.js only)

Cost: Free | Developer time saved: Significant

See Also: ADR-006: React vs Next.js

React Query (TanStack Query) ​

Status: ✅ Adopted | Category: Data Fetching | Health: 🟢 Excellent

Why React Query?

  • Intelligent caching and invalidation
  • Automatic refetching and background updates
  • Optimistic updates for instant UI
  • Request deduplication
  • Works perfectly with REST APIs

Metrics:

  • Version: 5.0+
  • Downloads: 3M+/month
  • Maintenance: ✅ Very active

Alternatives:

LibraryProsConsVerdict
SWRSimple, lightweightLess features, no devtools❌ Too simple for complex needs
RTK QueryRedux integrationRequires Redux, more boilerplate❌ Don't need Redux
Apollo ClientGreat for GraphQLOverkill for REST❌ Not using GraphQL

Cost: Free

TailwindCSS ​

Status: ✅ Adopted | Category: CSS Framework | Health: 🟢 Excellent

Why Tailwind?

  • Utility-first: rapid development
  • Small production bundle (purges unused)
  • Consistent design system
  • No naming conflicts
  • Excellent documentation

Metrics:

  • Version: 3.4+
  • Downloads: 10M+/month
  • Production bundle: ~10-20KB (after purge)

Alternatives:

  • styled-components (runtime cost, larger bundle)
  • CSS Modules (more boilerplate)
  • Bootstrap (opinionated, harder to customize)

Cost: Free

Radix UI ​

Status: ✅ Adopted | Category: Component Library | Health: 🟢 Excellent

Why Radix?

  • Unstyled primitives (full style control)
  • Accessibility built-in (ARIA, keyboard nav)
  • No CSS conflicts
  • Works perfectly with Tailwind

Used Components:

  • Dialog, DropdownMenu, Select, Tabs, Toast

Alternatives:

  • HeadlessUI (limited components)
  • MUI (opinionated styling, large bundle)
  • Ant Design (not medical-friendly design)

Cost: Free

Keycloakify ​

Status: ✅ Adopted | Category: Keycloak Theming | Health: 🟢 Good

Why Keycloakify?

  • React-based theme (same stack as frontend)
  • Type-safe, maintainable
  • Preview themes locally
  • Replaces Freemarker (Java templating)

Migration: Migrated from Freemarker in Oct 2025

See Also: ADR-002: Keycloakify Migration

Cost: Free

TipTap ​

Status: ✅ Adopted | Category: Rich Text Editor | Health: 🟢 Excellent

Why TipTap?

  • Headless (works with React)
  • JSON-based document format (stores in database)
  • Extensible with custom nodes
  • Medical-friendly (no markdown, clean UI)

Usage: Clinical note editor

Alternatives:

  • Draft.js (deprecated)
  • Slate.js (complex API)
  • Quill (not React-native)

Cost: Free (MIT license)

Infrastructure ​

PostgreSQL ​

Status: ✅ Adopted | Category: Database | Health: 🟢 Excellent

Why PostgreSQL?

  • ACID compliance (critical for medical data)
  • JSON/JSONB support (TipTap documents)
  • Excellent performance
  • Robust backup/replication
  • HIPAA-compliant deployments

Deployment: Google Cloud SQL

Alternatives:

  • MySQL (less feature-rich)
  • MongoDB (no ACID guarantees)
  • CockroachDB (overkill, expensive)

Cost: $15-80/month (Cloud SQL, depending on instance size)

Docker Compose ​

Status: ✅ Adopted | Category: Local Development | Health: 🟢 Excellent

Why Docker Compose?

  • Simple multi-service orchestration
  • Consistent dev environment
  • No Kubernetes complexity for local dev

Services: PostgreSQL, Keycloak

Alternatives:

  • Local installs (inconsistent environments)
  • Kubernetes (overkill for local)
  • Vagrant (slower, VM overhead)

Cost: Free

Terraform ​

Status: ✅ Adopted | Category: Infrastructure as Code | Health: 🟢 Excellent

Why Terraform?

  • Declarative infrastructure
  • Version-controlled configurations
  • Reproducible deployments
  • Multi-cloud support (GCP + Keycloak)

Usage:

  • GCP infrastructure (Cloud Run, Cloud SQL, VPC)
  • Keycloak realm configuration

Alternatives:

  • Pulumi (requires programming language knowledge)
  • CloudFormation (AWS-only)
  • Manual setup (error-prone, slow)

Time Savings: 2 minutes (Terraform) vs 45 minutes (manual)

See Also: ADR-004: Terraform for Keycloak

Cost: Free (open source)

Google Cloud Run ​

Status: ✅ Adopted | Category: Hosting | Health: 🟢 Excellent

Why Cloud Run?

  • Serverless containers (no server management)
  • Scale to zero (cost savings)
  • Multi-region deployment
  • VPC connectivity (private database)
  • Fast cold starts

Metrics:

  • Regions: Canada (northamerica-northeast1) + US (us-central1)
  • Cost: ~$10-60/month (depending on min instances)
  • Scaling: 0-10 instances per region

Alternatives:

PlatformProsConsVerdict
AWS ECSMatureMore complex, no scale-to-zero❌ More expensive
HerokuSimple$25-50/month minimum, less control❌ Expensive for what we need
RailwayDev-friendlyExpensive at scale, less enterprise-ready❌ Not production-proven
Fly.ioGlobal edgeLess mature, smaller ecosystem🟡 Viable alternative

Cost: $35-40/month (dev) | $145-195/month (production estimate)

Package Health Monitoring ​

Review Schedule ​

Package TypeReview FrequencyAction
Critical (auth, database)MonthlyCheck for security updates
Core (FastAPI, React)QuarterlyReview major version updates
Utilities (devtools)AnnuallyAssess if still needed

Security Monitoring ​

  • Dependabot: Enabled on GitHub
  • npm audit: Run before releases
  • Poetry security scan: Check for CVEs

Upgrade Policy ​

  • Security patches: Apply immediately
  • Minor versions: Review changelog, test, apply
  • Major versions: Evaluate breaking changes, ADR if significant

Cost Summary ​

Monthly Recurring Costs ​

CategoryPackageCost
External ServicesAnthropic Claude$50-150
Deepgram$75-150
Keycloak hosting (Cloud Run)$15-20
InfrastructureCloud SQL (PostgreSQL)$15-80
Cloud Run (backend)$10-60
Networking/VPC$5-10
Secret Manager$5
FrontendCloudflare Pages$0 (free tier)
Total (dev)$35-40
Total (prod est.)$175-470

Cost Savings vs Alternatives ​

  • Auth0 → Keycloak: $300/month saved = $3,600/year
  • Self-hosted Llama → Claude: Infrastructure savings ~$450/month
  • Heroku → Cloud Run: $15-30/month saved
  • Total annual savings: ~$4,000-5,000

Next Steps ​

Internal documentation for Noumaris platform

Copyright © 2025 Noumaris