ietf-draft-analyzer/data/reports/architecture-assessment-2026-03-09.md

IETF Draft Analyzer — Architectural Assessment

Date: 2026-03-09 Scope: Core source code analysis (src/, tests/) Project Size: ~7.6 MB, 19,662 lines of Python

---

1. File Sizes and Complexity

God Files (largest, highest complexity risk)

File	LOC	Severity	Issue
webui/data.py	4,360	HIGH	Service/data access layer doing too much
cli.py	3,438	MEDIUM	96 functions, 40+ Click commands, hard to navigate
reports.py	2,739	MEDIUM	Single Reporter class with many report generation methods
db.py	1,690	MEDIUM	100+ methods, schema + CRUD + business logic mixed

Healthy Modules (< 500 LOC, focused)

• models.py (104 LOC) — Domain models only
• config.py (108 LOC) — Configuration with env overrides
• embeddings.py (205 LOC) — Ollama embedding wrapper
• authors.py (137 LOC) — Author network fetching
• fetcher.py (204 LOC) — Datatracker API client

---

2. Module Boundaries: Core vs. Web

Clean Separation ✓

• Core layer (src/ietf_analyzer/): Self-contained, no Flask dependencies
• Web layer (src/webui/): Depends on core, not vice-versa
• No circular imports detected

Problem: webui/data.py Violates Single Responsibility

What it does:

1. Wraps Database (4,360 lines!)
2. Implements domain logic (clustering, readiness scoring, similarity graphs)
3. Prepares data for JSON/Jinja2 serialization
4. Defines TypedDicts for response shapes
5. Calls sklearn for TSNE/hierarchical clustering
6. Builds visualization data (radar, histogram, network graphs)

Risk: Tests only test_web_data.py — hard to regression-test domain logic when mixed with presentation layer.

---

3. Flask Structure (app.py)

Routes Count

• 72 functions (includes helpers)
• ~40+ @app.route() handlers
• No blueprints — monolithic Flask app

Route Categories

1. Overview pages (5) — /, /landscape, /timeline, /idea-clusters, /ratings
2. Detail pages (6) — /drafts, /drafts/<name>, /gaps, /gaps/<id>, etc.
3. Feature pages (8) — /search, /ask, /compare, /monitor, /admin/analytics, etc.
4. API endpoints (20+) — /api/drafts, /api/stats, /api/search, /api/ask, etc.
5. Helpers (5+) — auth, rate limiting, CSV export, DB context

Issues

Issue	Effort	Impact
No blueprint organization — Mix of concerns (pages, APIs, admin) in one file	SMALL	Makes navigation hard
Tight coupling to data.py — 50 imports from data.py	SMALL	Hard to refactor data layer
Mixed JSON/HTML rendering — Some routes render both based on Accept header	SMALL	Should be separate APIs
Admin functions inline — /admin/analytics uses @admin_required decorator	SMALL	Should be separate blueprint

Recommendation: Split into 4 blueprints:

• blueprints/pages.py — HTML pages
• blueprints/api.py — JSON endpoints
• blueprints/admin.py — Admin routes
• blueprints/helpers.py — Shared utilities

---

4. Database Layer (db.py)

Structure: Single Database Class

100+ methods doing:

1. Schema definition — SCHEMA constant, ensure_tables()
2. CRUD operations — add_draft(), update_draft(), get_draft(), delete_draft()
3. Bulk operations — add_drafts(), update_ratings()
4. Complex queries — get_drafts_by_category(), search_fts(), most_cited(), co_authors()
5. Business logic — Rating aggregations, clustering, similarity ranking
6. Cache management — llm_cache table operations
7. Stats — count_drafts(), count_by_source(), aggregations

Issues

Issue	Evidence	Refactor Effort
Mixed concerns	Methods scattered: schema, CRUD, queries, business logic	LARGE
No transaction support	add_draft() does 3+ INSERT statements without explicit tx	MEDIUM
Hard to unit test	Database class touches 8+ tables; need fixtures for each	MEDIUM
Tight coupling to models	Direct Author, Draft, Rating dataclass deps	SMALL
No query builders	Raw SQL in 20+ methods (injection risk if not careful)	MEDIUM

Refactoring Path (4-step)

# Current: db.Database (100 methods)
#
# Refactored:
# - db.Schema — @dataclass fixtures, schema def (10 methods)
# - db.Repository — CRUD base class (15 methods)
# - db.DraftRepository, AuthorRepository, etc. — domain-specific CRUD
# - db.Queries — Complex queries as static methods or separate class
# - db.Cache — LLM cache operations (10 methods)

Effort: LARGE (4+ hours) Benefit: Testability, reusability, transaction support, easier migrations

---

5. Pipeline Architecture (pipeline/)

Structure: Modular design ✓

• context.py — ContextBuilder (domain logic for draft generation)
• generator.py — DraftGenerator (Claude-based content generation)
• family.py — Family/relationships logic
• formatter.py — Output formatting
• quality.py — Quality checks
• prompts.py — System prompts
• PROMPTS constant — Shared across modules

Assessment

✓ Good separation — Each module has a single responsibility ✓ Testable — Pure functions + dependency injection via Config/Database ✓ Extensible — Can add new stages without touching existing code

No refactoring needed for pipeline itself.

---

6. Sources Architecture (sources/)

Structure: Plugin pattern ✓

• base.py — SourceDocument dataclass, SourceFetcher protocol
• ietf.py, w3c.py, etsi.py, itu.py, iso.py, nist.py — Concrete fetchers

Assessment

✓ Excellent separation — Base protocol + concrete implementations ✓ Testable — Mock fetchers easy to create ✓ Extensible — New source = new file, no changes to orchestrator

No refactoring needed.

---

7. Config Management (config.py)

Structure

• Single Config dataclass (40 fields)
• load() class method with env var override support
• save() method to persist to JSON
• Validation in _validate()

Assessment

✓ Clean — Single responsibility ✓ Testable — No I/O except file read/write ✓ Env support — _ENV_OVERRIDES dict maps env vars

Minor issue: Could use structured logging of which env vars override config (currently silent).

No refactoring needed unless config grows beyond 50 fields.

---

8. CLI Structure (cli.py)

Count: 96 functions

Command groups:

• fetch — Datatracker + multi-source fetching
• classify — Ollama-based pre-filtering
• list, search, show, annotate — Draft browsing
• analyze — Claude analysis (rate, ideas, gaps)
• ask, compare — Interactive queries
• embed, embed-ideas — Ollama embeddings
• similar, clusters — Embedding-based search
• report (group) → overview, landscape, digest, timeline, etc.
• monitor — Background pipeline automation
• pipeline, pipeline-status, pipeline-auto-heal — Orchestration
• observatory — Multi-source dashboard
• readiness — Release readiness analysis
• export — Generate drafts from gaps
• web — Flask app launcher

Issues

Issue	Severity	Solution
96 functions in one file	MEDIUM	Hard to navigate, should split into subcommands or files
Long help text inline	LOW	Could use .help-txt files for docstrings
Late imports	LOW	Some imports inside @pass_cfg_db functions to save startup time (OK pattern)
Global console object	LOW	OK for Click, allows colorized output

Recommended Split (5 files)

# cli.py (main entry, 200 lines)
# └─ cli/fetching.py (fetch, classify) — 400 lines
# └─ cli/analysis.py (analyze, ask, compare) — 600 lines
# └─ cli/reporting.py (report *, export, observatory) — 800 lines
# └─ cli/admin.py (monitor, pipeline, web) — 400 lines

Effort: SMALL (1 hour) Benefit: Easier to navigate, faster to find commands, clearer testing boundaries.

---

9. Circular Dependencies

Check Results

✓ No circular imports detected

• cli.py → db, config, models ✓
• app.py → webui.data, webui.auth, ietf_analyzer.* ✓
• webui.data → ietf_analyzer.db, ietf_analyzer.config ✓
• db.py → models, config ✓

---

10. Test Structure

Test files: 8 modules covering:

• test_db.py — Database operations
• test_analyzer.py — Claude analysis
• test_search.py — Similarity + FTS
• test_web_data.py — Data layer for web
• test_models.py — Domain models
• test_obsidian_export.py — Export

Coverage gaps:

• No tests for cli.py (big commands, hard to test without mocking db)
• No tests for app.py routes (would need Flask test client + fixtures)
• No tests for pipeline modules (context, generator, family)
• No tests for sources (would need HTTP mocks)

Effort to add 30% CLI coverage: MEDIUM (2-3 hours)

---

Summary: Refactoring Roadmap

Priority	Module	Issue	Effort	Benefit
HIGH	webui/data.py	4,360 LOC, mixed concerns (CRUD + domain logic + presentation)	LARGE	Separates presentation from domain, enables better testing
MEDIUM	db.py	100 methods, mixed schema/CRUD/logic	LARGE	Testability, transaction support, query builders
MEDIUM	cli.py	96 functions, hard to navigate	SMALL	Better organization, easier to find commands
MEDIUM	app.py	40+ routes, no blueprints	SMALL	Clearer structure, easier to refactor
LOW	Config	40 fields, working well	NONE	Monitor for growth beyond 50 fields
LOW	Pipeline/Sources	Well-structured, testable	NONE	No changes needed

---

Recommendations (Priority Order)

1. Extract webui/data.py → presentation + domain (4 hours)

webui/
├── data.py (current 4,360 → 1,000) — Only JSON serialization
└── services/
    ├── drafts.py (200) — Draft filtering/sorting logic
    ├── analytics.py (400) — Dashboard stats + visualizations
    ├── search.py (300) — Search + clustering
    └── readiness.py (200) — Readiness scoring

Cost: 4 hours Benefit: Can reuse analytics for CLI reports, easier to test

2. Refactor db.py → Repository pattern (4 hours)

db/
├── __init__.py (exports Database facade)
├── schema.py (100) — Schema definition
├── repository.py (200) — Base CRUD class
├── drafts.py (300) — DraftRepository (get, add, update, delete drafts)
├── ratings.py (200) — RatingRepository
├── authors.py (150) — AuthorRepository
├── queries.py (400) — Complex queries (search, similarity, aggregations)
└── cache.py (150) — LLM cache operations

Cost: 4 hours Benefit: 80% reduction in method count per class, transaction support, testability

3. Split cli.py into subcommand groups (1 hour)

cli/
├── __init__.py (main entry, ~200 lines)
├── fetching.py (fetch, classify)
├── analysis.py (analyze, ask, compare)
├── reporting.py (report *, export, observatory)
└── admin.py (monitor, pipeline, web)

Cost: 1 hour Benefit: Easier to navigate, clearer boundaries, faster to find commands

4. Convert Flask app to blueprints (1.5 hours)

webui/
├── app.py (core Flask setup, ~100 lines)
└── blueprints/
    ├── pages.py (HTML routes: /, /drafts, /landscape, etc.)
    ├── api.py (JSON endpoints: /api/*)
    ├── admin.py (/admin/*)
    └── helpers.py (rate limiting, auth, CSV export)

Cost: 1.5 hours Benefit: Clearer separation of concerns, easier to add/remove features

5. Add CLI tests (3 hours)

• Mock database for each command
• Test success paths + error cases
• Quick smoke tests for all 15+ major commands

Cost: 3 hours Benefit: Catch regressions early, safe refactoring

---

Current State Assessment

Dimension	Score	Notes
Modularity	7/10	Good separation of concerns; core vs. web clean; webui/data.py is the weak point
Testability	6/10	DB layer hard to unit test; pipeline/sources good; no CLI tests
Maintainability	6/10	Many large files; well-documented; consistent patterns throughout
Extensibility	8/10	Plugin pattern for sources; easy to add new reports; CLI is open-ended
Performance	8/10	Caching, FTS5, lazy imports in CLI; no N+1 queries detected

Overall: 7/10 — Production-ready but showing signs of technical debt accumulation.

The project is well-organized at a high level but needs refactoring of large monolithic files to stay maintainable as it grows. The webui/data.py and db.py files should be prioritized first.