# 🔍 DRY ARCHITECTURE AUDIT COMPLETE - NO FILES MODIFIED

# P0 Deep Reconnaissance: Unified Address & Search Architecture Audit

## Metadata
- **Audit Date:** 2026-07-01
- **Scope:** Backend models, Frontend components, Phone validation, Search APIs
- **Status:** Reconnaissance complete — recommendations ready for Architect review
- **Files Modified:** 0 (zero)

---

## Table of Contents
1. [Backend Address Models — Current State](#1-backend-address-models--current-state)
2. [Frontend Reusable Components — Address/Phone](#2-frontend-reusable-components--addressphone)
3. [Phone Number Validation — Audit](#3-phone-number-validation--audit)
4. [Search APIs — Current State](#4-search-apis--current-state)
5. [Duplication Summary Table](#5-duplication-summary-table)
6. [Priority Recommendations](#6-priority-recommendations)

---

## 1. Backend Address Models — Current State

### 1.1 The Dedicated `system.addresses` Table (`/backend/app/models/identity/address.py:39`)

A proper **Address model already exists** in the `system` schema:

```python
class Address(Base):
    __tablename__ = "addresses"
    __table_args__ = {"schema": "system"}
    id: Mapped[uuid.UUID] = mapped_column(PG_UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    postal_code_id: Mapped[Optional[int]] = mapped_column(Integer, ForeignKey("system.geo_postal_codes.id"))
    street_name: Mapped[Optional[str]] = mapped_column(String(200))
    street_type: Mapped[Optional[str]] = mapped_column(String(50))
    house_number: Mapped[Optional[str]] = mapped_column(String(20))
    hrsz: Mapped[Optional[str]] = mapped_column(String(50))
    plus_code: Mapped[Optional[str]] = mapped_column(String(50))
    latitude: Mapped[Optional[float]] = mapped_column(Float(53))
    longitude: Mapped[Optional[float]] = mapped_column(Float(53))
    postal_code: Mapped[Optional["GeoPostalCode"]] = relationship(lazy="joined")
```

It has **convenience properties** (`zip`, `city`) via the `GeoPostalCode` relationship and supports **GPS coordinates**.

**Supporting lookup tables:**
- `GeoPostalCode` — zip/city pairs at `address.py:12`
- `GeoStreet` — street names at `address.py:22`
- `GeoStreetType` — street type codes (utca, tér, etc.) at `address.py:31`

### 1.2 Who Uses It Correctly?

**Only `Person`** at `/backend/app/models/identity/identity.py:105`:

```python
class Person(Base):
    ...
    address_id: Mapped[Optional[uuid.UUID]] = mapped_column(PG_UUID(as_uuid=True), ForeignKey("system.addresses.id"))
    address: Mapped[Optional["Address"]] = relationship(lazy="joined")
```

**Person** has no denormalized address fields — it relies **entirely** on the FK to `system.addresses`.

### 1.3 Who Bypasses It (The Violations)

#### **Organization** (`/backend/app/models/marketplace/organization.py:73`) — **WORST OFFENDER**

Despite having `address_id: Mapped[Optional[uuid.UUID]]` (FK to `system.addresses`), Organization also stores **17 additional denormalized address fields** across 3 address blocks:

| Block | Fields | Count |
|-------|--------|-------|
| **Main address** | `address_zip`, `address_city`, `address_street_name`, `address_street_type`, `address_house_number`, `address_hrsz`, `plus_code` | 7 |
| **Billing address** | `billing_zip`, `billing_city`, `billing_street_name`, `billing_street_type`, `billing_house_number` | 5 |
| **Notification address** | `notification_zip`, `notification_city`, `notification_street_name`, `notification_street_type`, `notification_house_number` | 5 |
| **Total** | | **17** |

#### **Branch** (`/backend/app/models/marketplace/organization.py:324`) — **9 denormalized fields + PostGIS**

Despite having `address_id: Mapped[Optional[uuid.UUID]]` (FK), Branch duplicates:
`postal_code`, `city`, `street_name`, `street_type`, `house_number`, `stairwell`, `floor`, `door`, `hrsz`

Additionally, `location: Mapped[Optional[Any]] = mapped_column(Geometry(geometry_type='POINT', srid=4326))` for PostGIS geospatial queries.

#### **ServiceStaging** (`/backend/app/models/marketplace/service.py:170`) — **3 denormalized fields, NO FK**

```python
class ServiceStaging(Base):
    ...
    postal_code: Mapped[Optional[str]] = mapped_column(String(20))
    city: Mapped[Optional[str]] = mapped_column(String(200))
    full_address: Mapped[Optional[str]] = mapped_column(String(500))
```

**No FK to `system.addresses` at all.** These are raw string fields.

### 1.4 Summary of Address Column Duplication

| Model | FK to Address | Denormalized Fields | PostGIS |
|-------|:------------:|:-------------------:|:-------:|
| `Person` | ✅ Yes | 0 | ❌ |
| `Organization` | ✅ Yes (underutilized) | 17 | ❌ |
| `Branch` | ✅ Yes (underutilized) | 9 | ✅ `Geometry(POINT)` |
| `ServiceStaging` | ❌ **No** | 3 | ❌ |
| **TOTAL** | | **29 duplicated fields** | |

---

## 2. Frontend Reusable Components — Address/Phone

### 2.1 Existing Components (`/frontend_admin/components/`)

Only 3 components exist:
- `LanguageSwitcher.vue` — i18n language selector
- `TreeNode.vue` — recursive tree for category selection
- `garages/` — 3 sub-components for garage management

**NO** `AddressForm.vue`, `PhoneInput.vue`, or any address/phone UI component exists.

### 2.2 Existing Composables (`/frontend_admin/composables/useFormatter.ts`)

Only `useFormatter.ts` — handles `formatNumber`, `formatCurrency`, `formatDate`, `formatDateTime`, `formatPercent`, `formatPriceWithVat`.

**NO** address formatting, phone formatting, or phone validation composable.

### 2.3 How Address Is Currently Rendered (Copy-Paste Pattern)

Example from `/frontend_admin/providers/[id]/edit.vue` — the edit page manually defines:
- `city` (text input)
- `address_zip` (text input)
- `address_street_name` (text input)
- `address_street_type` (text input)
- `address_house_number` (text input)
- `plus_code` (text input)
- `contact_phone` (text input)
- `contact_email` (email input)

This same **copy-paste pattern** is repeated across:
- Person edit pages
- Organization edit pages
- Provider edit pages

### 2.4 Assessment

**Code duplication is severe.** Every form manually re-declares address fields. There is no:
- Reusable `AddressForm.vue` component
- Reusable `PhoneInput.vue` component
- Address autocomplete UI
- Phone number formatting component

---

## 3. Phone Number Validation — Audit

### 3.1 All Phone Field Locations (7 locations found)

| File | Model/Schema | Field | Type | Validation |
|------|-------------|-------|------|:----------:|
| `identity.py:100` | `Person` | `phone` | `Mapped[str]` | **None** |
| `organization.py:95` | `Organization` | `phone` | `Mapped[str]` | **None** |
| `organization.py:340` | `Branch` | `phone` | `Mapped[str]` | **None** |
| `service.py:40` | `ServiceProfile` | `contact_phone` | `Mapped[str]` | **None** |
| `service.py:180` | `ServiceStaging` | `contact_phone` | `Mapped[str(50)]` | **None** |
| `provider.py` (schemas) | `ProviderQuickAddIn` | `phone` | `Optional[str]` | **None** |
| `provider.py` (schemas) | `ProviderUpdateIn` | `phone` | `Optional[str]` | **None** |

### 3.2 Dependencies Check

```bash
# requirements.txt check — NO phone library found
grep -i phone backend/requirements.txt  # empty result
```

- **`phonenumbers`/`phonenumberslite`**: ❌ Not installed
- **Pydantic phone validator**: ❌ Not used
- **Custom regex validator**: ❌ Not present
- **E.164 format enforcement**: ❌ Not done

### 3.3 Assessment

**Phone numbers are completely unvalidated** across the entire codebase. They are stored as arbitrary `String` columns with at most `max_length=50`. The Google Places API returns `internationalPhoneNumber` in E.164 format, but nothing enforces this.

### 3.4 Impact

- `Person.phone` stores user registration phone numbers
- `Organization.phone` stores company contact numbers
- `Branch.phone` stores branch-specific contact numbers
- `ServiceProfile.contact_phone` stores service provider contact
- `ServiceStaging.contact_phone` stores unverified provider contact

**Without validation:** garbage data, formatting inconsistencies, SMS delivery failures, international dialing issues.

---

## 4. Search APIs — Current State

### 4.1 Endpoint Inventory

| # | Endpoint | Path | Params | Geospatial | ILIKE | Pagination |
|:-:|----------|------|--------|:----------:|:-----:|:----------:|
| 1 | `search.py:14` | `GET /api/v1/search/match` | `lat`, `lng`, `radius_km`, `sort_by` | ✅ `ST_DWithin` + `ST_DistanceSphere` | ❌ | ❌ |
| 2 | `providers.py:184` | `GET /api/v1/providers/search` | `q`, `category`, `city`, `category_ids`, `org_type`, `limit`, `offset` | ❌ | ✅ (name) | ✅ |
| 3 | `services.py:112` | `GET /api/v1/services/search` | `expertise_key`, `city`, `min_confidence` | ❌ | ✅ (city) | ❌ |
| 4 | `admin.py:923` | `GET /api/v1/admin/organizations/search` | `name`, `limit` | ❌ | ✅ (3 name fields) | ❌ |

### 4.2 Detailed API Signatures

#### 4.2.1 `GET /api/v1/search/match` (`/backend/app/api/v1/endpoints/search.py:14`)
```python
async def match_service(
    lat: float = Query(...),
    lng: float = Query(...),
    radius_km: float = Query(10.0),
    sort_by: str = Query("distance")
) -> dict:
```
- **What it returns:** Organization `id`, `name`, rating, `branch_id`, `city`, `distance`
- **Why it exists:** Geofencing for the public "find nearest service" feature
- **Missing:** No text search, no category filter, no pagination

#### 4.2.2 `GET /api/v1/providers/search` (`/backend/app/api/v1/endpoints/providers.py:184`)
```python
async def search_service_providers(
    q: Optional[str] = None,
    category: Optional[str] = None,
    city: Optional[str] = None,
    category_ids: Optional[str] = None,  # comma-separated
    org_type: Optional[str] = None,
    limit: int = Query(20),
    offset: int = Query(0)
) -> ProviderSearchResponse:
```
- **What it does:** Multi-source search across `verified_org`, `staged_data`, `crowd_added`
- **Why it's limited:** No geospatial component, only ILIKE on name
- **SQL excerpt (providers.py:210-240):**
  ```python
  query = query.where(ServiceProvider.name.ilike(f"%{q}%"))
  ```
- **Missing:** No `ST_DWithin`, no radius filter, no distance sorting

#### 4.2.3 `GET /api/v1/services/search` (`/backend/app/api/v1/endpoints/services.py:112`)
```python
async def search_services(
    expertise_key: Optional[str] = None,
    city: Optional[str] = None,
    min_confidence: Optional[float] = None
) -> list:
```
- **What it does:** Filters by `ExpertiseTag.key` and city ILIKE
- **Why it's limited:** No location awareness, no pagination, no distance
- **Missing:** No PostGIS, no radius

#### 4.2.4 `GET /api/v1/admin/organizations/search` (`/backend/app/api/v1/endpoints/admin.py:923`)
```python
async def search_organizations(
    name: str = Query(...),
    limit: int = Query(50)
) -> list:
```
- **What it does:** Simple ILIKE on 3 name fields for admin autocomplete
- **Missing:** No filters, no pagination, no geolocation

### 4.3 Database Index Audit

```sql
-- Check for pg_trgm extension (enables fuzzy ILIKE indexing)
SELECT * FROM pg_extension WHERE extname = 'pg_trgm';
```
**Result:** ❌ `pg_trgm` extension is **NOT installed**

```sql
-- Check for GIN or GiST indexes on name/city columns
SELECT indexname, indexdef FROM pg_indexes WHERE tablename IN ('service_providers', 'organizations', 'branches', 'service_staging');
```
**Expected:** No trigram indexes exist — all ILIKE queries perform **full table scans**.

### 4.4 Assessment

**4 fragmented search endpoints** with no unified design:
1. Only `search/match` uses PostGIS
2. `providers/search` has pagination but no geolocation
3. `services/search` has neither
4. No trigram indexing → ILIKE scans will degrade with data growth
5. No full-text search (tsvector)
6. No hybrid search combining text relevance + distance

---

## 5. Duplication Summary Table

| Component | DRY Status | Duplicated Fields | Missing Abstraction |
|-----------|:----------:|:-----------------:|---------------------|
| `Organization` address | ❌ **17 copies** | zip, city, street_name, street_type, house_number (×3 blocks) | `AddressMixin` |
| `Branch` address | ❌ **9 copies** | postal_code, city, street_name, street_type, house_number, stairwell, floor, door, hrsz | `AddressMixin` |
| `ServiceStaging` address | ❌ **3 copies** | postal_code, city, full_address | FK to `system.addresses` |
| Phone fields (7 locations) | ❌ **7 copies** | `phone`/`contact_phone` as unvalidated string | `PhoneValidator` |
| Frontend address forms | ❌ **copy-paste** | 8 field blocks repeated | `AddressForm.vue` |
| Frontend phone inputs | ❌ **copy-paste** | `contact_phone` input | `PhoneInput.vue` |
| Search APIs | ❌ **4 endpoints** | Different params, no unified design | `SmartSearchEngine` |

---

## 6. Priority Recommendations

### P1 — Create `AddressMixin` (Backend)
**File to create:** `/backend/app/models/mixins/address_mixin.py`

Consolidate all 29 duplicated address fields into a single SQLAlchemy mixin. All models (`Organization`, `Branch`, `ServiceStaging`) should use it.

### P1 — Normalize `ServiceStaging` to use `system.addresses`
**Files to modify:** `/backend/app/models/marketplace/service.py`, related schemas

Add `address_id: FK → system.addresses.id` to `ServiceStaging`. Drop raw `postal_code`, `city`, `full_address` columns.

### P2 — Create `PhoneValidator` (Backend Core)
**File to create:** `/backend/app/core/validators.py`

Add E.164 regex validation. Apply to all 7 phone field locations. Alternatively, install `phonenumberslite` library.

### P2 — Create `AddressForm.vue` + `PhoneInput.vue` (Frontend)
**Files to create:** `/frontend_admin/components/AddressForm.vue`, `/frontend_admin/components/PhoneInput.vue`

Consolidate the copy-pasted address and phone form fields into reusable components.

### P3 — Unified Smart Search Engine
**Files to create:** `/backend/app/services/smart_search_service.py`, updated endpoints

Consolidate 4 search endpoints into one service with:
- `pg_trgm` extension + GIN indexes for fuzzy text matching
- `ST_DWithin` for geospatial filtering
- Hybrid scoring (text relevance × distance)
- Unified pagination
- Category/expertise filtering

---

## Appendix A: Key Files Referenced

| File | Purpose |
|------|---------|
| `backend/app/models/identity/address.py` | Core `Address`, `GeoPostalCode`, `GeoStreet`, `GeoStreetType` models |
| `backend/app/models/identity/identity.py` | `Person` model (clean address usage via FK) |
| `backend/app/models/marketplace/organization.py` | `Organization` (17 duplicated fields), `Branch` (9 duplicated fields + PostGIS) |
| `backend/app/models/marketplace/service.py` | `ServiceProfile`, `ServiceStaging` (3 raw fields, no FK) |
| `backend/app/schemas/provider.py` | `ProviderSearchResult`, `ProviderQuickAddIn`, `ProviderUpdateIn` |
| `backend/app/schemas/organization.py` | `CorpOnboardIn`, `OrganizationUpdate`, `OrganizationResponse` |
| `backend/app/schemas/user.py` | `AddressResponse`, `PersonResponse`, `PersonUpdate` |
| `backend/app/api/v1/endpoints/search.py` | Geofencing search (`GET /api/v1/search/match`) |
| `backend/app/api/v1/endpoints/providers.py` | Multi-source provider search (`GET /api/v1/providers/search`) |
| `backend/app/api/v1/endpoints/services.py` | Expertise-based search (`GET /api/v1/services/search`) |
| `backend/app/api/v1/endpoints/admin.py` | Admin org search (`GET /api/v1/admin/organizations/search`) |
| `frontend_admin/composables/useFormatter.ts` | Only existing composable (no address/phone logic) |

---

*Audit complete. 0 files modified. Next step: Architect review and logic_spec creation for P1 items.*