service-finder/docs/p0_address_manager_usage_audit_2026-07-01.md

P0 Architecture Audit: AddressManager Usage Verification

Date: 2026-07-01
Auditor: Rendszer-Architect
Scope: Backend models, services, endpoints
Goal: Verify that no direct SQL/ORM inserts/updates are bypassing the AddressManager

---

1. Model Analysis

✅ Organization (backend/app/models/marketplace/organization.py)

• Status: CLEAN — Zero denormalized address fields
• Uses only FK columns: address_id, billing_address_id, notification_address_id → system.addresses.id
• Has proper SQLAlchemy relationship definitions for all three address types

✅ Branch (backend/app/models/marketplace/organization.py:324-366)

• Status: CLEAN — Zero denormalized address fields
• Uses only address_id FK → system.addresses.id

✅ ServiceStaging (in backend/app/models/marketplace/service.py:170-195)

• Status: CLEAN — Uses address_id FK → system.addresses.id

✅ Address (backend/app/models/identity/address.py:39-74)

• Status: CLEAN — Uses proper FK-based architecture
• zip and city are properties resolved via the postal_code relationship

⚠️ ServiceProvider (backend/app/models/identity/social.py:23-71)

• Status: INTENTIONAL DENORMALIZATION — Contains flat address fields
• Marked "P0 HYBRID VENDOR REFACTOR" design choice

---

2. Critical Bugs Found

🔴 P0 CRITICAL: admin.py:943 — Organization.address_city REMOVED from ORM

File: backend/app/api/v1/endpoints/admin.py:943

The search_organizations_by_name endpoint selects Organization.address_city which is not defined in the Organization SQLAlchemy model. SQLAlchemy will raise an error at runtime.

Impact: Admin organization search (/admin/organizations/search?name=...) is broken.

🟡 P1: admin_persons.py:670-699 — Direct Address writes bypassing AddressManager

Directly writes address.street_name = ... without calling AddressManager.create_or_update(). No postal_code_id resolution.

🟡 P1: admin_organizations.py — Flat address fields silently ignored

OrganizationUpdate schema has address_zip, address_city etc. but hasattr(org, "address_zip") returns False → silently ignored.

---

3. Database Ghost Columns

The following old denormalized columns still exist in fleet.organizations table but have NO ORM mapping: address_city, address_zip, address_street_name, address_street_type, address_house_number, address_hrsz, billing_city/zip/street_name/street_type, notification_city/zip/street_name/street_type

---

4. Summary

Severity	Issue	File:Line
🔴 P0	Organization.address_city removed from ORM, still referenced	admin.py:943
🟡 P1	Direct Address writes bypassing AddressManager	admin_persons.py:670-699
🟡 P1	Flat address fields silently ignored on update	admin_organizations.py:1242-1343
🟡 P2	Ghost columns in DB from old schema	fleet.organizations
✅ PASS	Organization model uses FKs only	organization.py
✅ PASS	Branch model uses FK only	organization.py:333
✅ PASS	admin_organizations.py correctly uses AddressManager	admin_organizations.py:1313-1335
✅ PASS	Address model properly normalized	address.py