cleanup opportunities complexity hotspots

Complexity hotspots

The largest source files in the 360Ghar backend. Size is not always a problem - some files are large because they own a complex domain - but these are the first places to look when considering decomposition.

Active contributors: Saksham, Ravi

Top 5 by line count

File	Lines	What it does
app/services/user.py	951	User CRUD, phone normalization, preferences, role escalation, soft-delete, keyset pagination. Largest service file.
app/services/blog.py	930	Blog post CRUD, SEO field auto-computation (meta_title, meta_description, focus_keyword, canonical_url, og_image_url, reading_time_minutes, word_count), category and tag management.
app/services/storage/service.py	723	Cloudinary upload, download, delete, signed URL generation, folder path conventions. Wraps app/services/cloudinary/.
app/services/property/search.py	707	Property search: geospatial filters, full-text search, hybrid vector+text scoring, cursor pagination, sort options.
app/services/ai_agent/tools/owner.py	676	AI agent owner tools: property list/create/get/update, lease list/get/terminate, rent status/record/history, maintenance list/update.

Observations

• user.py is the churn hotspot (13 commits in the last 90 days). It has accreted phone normalization, preference management, and cursor pagination. A split into user_crud.py, user_preferences.py, and user_auth_sync.py would reduce merge conflicts, but the functions are tightly coupled and the split would require careful interface design.
• blog.py is large because SEO field computation is non-trivial. The SEO helpers could extract into app/services/blog_seo.py without changing behavior.
• storage/service.py wraps Cloudinary and could be split by operation type (upload, transform, delete), but the current single-file layout makes it easy to grep.
• property/search.py is large because search is genuinely complex (geospatial + FTS + vector + cursor). The PropertyQueryBuilder in app/repositories/property_query_builder.py already absorbs some of the query construction. Further decomposition should follow ADR 002 (repository protocols).
• ai_agent/tools/owner.py mirrors the owner MCP tools. It is large because the owner surface is large. Splitting by sub-domain (properties, leases, rent, maintenance) would match the app/mcp/chatgpt/pm_*_tools.py decomposition already in place.

ADR alignment

The ADRs in docs/adrs/ propose structural changes that would naturally decompose these files:

• ADR 001 (domain modules) would move user.py into app/modules/user/service.py alongside its models, schemas, and tests.
• ADR 002 (repository protocols) would extract query logic from property/search.py into a PropertySearchRepository protocol.
• ADR 004 (external service adapters) would extract Cloudinary calls from storage/service.py behind a StorageAdapter protocol.

These are target-state changes, not quick wins. See background/design-decisions.md.