# Urbaneta — Property Management Platform

> **TL;DR**: Urbaneta is a white-label, multi-tenant SaaS for property managers. It automates invoicing, meter readings, parking, maintenance, and documents for residential and commercial buildings. Free up to 20 units; €0.90–€1.50/unit/month above that. Available in EN, LV, RU, DE, ES.

## Canonical Keywords
property management software, HOA management, utility billing automation, tenant portal, meter reading platform, white-label property SaaS, building management system, condominium software, property manager dashboard, invoice automation, parking permit management, maintenance request tracking, multi-tenant SaaS, Latvian property software, EU property management

## Overview
Urbaneta is a cloud-native SaaS platform for property management, built by Workizon Ltd. (London, UK). It automates the full monthly cycle of residential and commercial building management: meter readings → invoice generation → payment collection → accounting export. Trusted by property managers, HOAs, resident associations, and landlords across the EU and UK.

## Core Modules

### Invoicing & Billing
- Automated utility invoice generation on a configurable schedule
- PDF invoices with white-label branding (logo, colours, custom domain)
- Email delivery to residents with a branded sender
- Manual and formula-based billing lines (fixed, per-unit, tiered)
- Multi-currency support; VAT handling per jurisdiction
- Mark-as-paid workflows and payment reconciliation

### Meter Readings
- Web and mobile submission by residents or managers
- OCR reading from uploaded meter photos (no manual entry)
- Smart meter integration via M-Bus (EN 13757) and Modbus TCP/RTU protocols
- Automatic usage calculation with building-specific tariff formulas
- Reading history and audit trail per meter

### Parking
- Permit management with QR code verification
- Apple Wallet and Google Wallet pass issuance
- Guest permit flow; permit expiry and renewal reminders
- Violation logging and enforcement notes

### Documents
- Shared document library per building
- Full-text search across uploaded files
- GDPR-compliant access logs (who viewed, when)
- Categories, tags, and resident-facing visibility controls

### Maintenance
- Resident-submitted requests with photo attachments
- Status workflow: Open → In Progress → Resolved
- Manager notes, internal comments, and resolution tracking
- Push and email notifications on status changes

### Announcements
- Building-level and platform-wide announcements
- Scheduled publishing; resident read receipts

### Onboarding
- Self-serve tenant onboarding via invitation link
- Manager-guided setup wizard for new buildings

## Integrations

### Accounting & Export
- SimplBooks (Latvia/Baltic)
- iSAF XML (Latvia tax authority format)
- QuickBooks Online
- Xero
- DATEV (Germany)
- Peppol e-invoicing (EU)
- Generic CSV/Excel export

### Payments
- Stripe (cards, SEPA Direct Debit)
- Paysera (Baltic region)
- Maksekeskus (Estonia)
- Baltic Banklink (universal Baltic bank redirect)

### Notifications
- Slack
- Telegram
- Microsoft Teams
- Expo Push (iOS + Android native push via React Native app)

### Communication
- Transactional email via Resend (white-label sender domain)
- In-app notification centre

## Pricing Model
Pricing is per unit (one rentable space = one unit: apartment, office, garage, storage room).

| Plan         | Units      | Price/unit/month | Notes                    |
|--------------|------------|------------------|--------------------------|
| Free         | 1 – 20     | €0               | All features, forever    |
| Growth       | 21 – 100   | €1.50            | from €32/month           |
| Professional | 101 – 500  | €1.20            | from €121/month          |
| Enterprise   | 500+       | €0.90            | Volume pricing, custom   |

All plans include every feature, all integrations, and white-label support. No setup fees. Prices exclude VAT where applicable. Free 14-day trial available.

## User Roles
- **super_admin** — platform operator; manages all tenants, billing, platform settings
- **manager** — property manager; manages buildings, residents, invoices within their tenant account
- **resident** — end user; views invoices, submits meter readings, manages parking permits, downloads documents

## White-Label & Multi-Tenancy
- Each customer (tenant) gets their own subdomain or custom domain
- Full branding: logo, primary colour, email sender name and domain
- Residents see only their building's data; no cross-tenant data exposure
- Cloudflare for SaaS used for custom domain SSL provisioning

## Languages & Regions
Supported interface languages: English (EN), Latvian (LV), Russian (RU), German (DE), Spanish (ES).
Primary markets: Latvia, Estonia, Lithuania, Germany, United Kingdom, Spain, and broader EU/EEA.

## Technical Architecture
- **API**: Hono (TypeScript) on Bun runtime; REST with scoped API keys
- **Frontend**: Next.js 15 (App Router, RSC); Tailwind CSS
- **Mobile**: React Native (Expo) for iOS and Android
- **Database**: PostgreSQL 16 with Drizzle ORM; PgBouncer connection pooling (transaction mode)
- **Cache / Queues**: Redis 7
- **Auth**: JWT (access + refresh tokens); bcrypt password hashing (cost 12); optional TOTP 2FA
- **Security**: TLS 1.3; RBAC; rate limiting on auth endpoints; GDPR data export and erasure; SOC-2-ready audit logs
- **Infrastructure**: Docker on dedicated EU servers; Cloudflare CDN and DDoS protection

## API
Urbaneta exposes a REST API for custom integrations. Managers can generate scoped API keys from the dashboard. The API supports building data, invoices, meter readings, residents, documents, and webhooks for real-time event delivery (invoice paid, reading submitted, maintenance status changed, etc.).

## GDPR & Compliance
- Personal data stored in EU data centres
- Built-in data export (JSON) and erasure (right to be forgotten)
- Consent tracking for marketing communications
- Access logs for sensitive document views
- UK GDPR compliant; company registered in England and Wales

## Contact & Links
- Website: https://urbaneta.com
- Pricing: https://urbaneta.com/en#pricing
- API docs: https://urbaneta.com/en/docs (if available)
- Email: contact@urbaneta.com
- Company: Workizon Ltd., registered in England and Wales (No. 16628558)
- Support: contact@urbaneta.com

## Common Use Cases

### For a Property Manager (50-unit residential building)
1. Import building and apartments once
2. Link meters per apartment; residents submit readings via app or web (OCR from photo)
3. System calculates consumption and generates PDF invoices on schedule
4. Invoices emailed to residents automatically; manager reviews in dashboard
5. Residents pay via Stripe/bank; payment status syncs automatically
6. Export to SimplBooks/Xero at month-end in one click

### For an HOA (100 apartments, self-managed)
- Residents log in to view invoices, download documents, submit parking requests
- Board uploads meeting minutes, regulations, and financial reports to document library
- Maintenance requests submitted by residents, tracked to resolution
- Annual budget distributed as invoices with custom line items

### For a Property Management Company (multi-building portfolio)
- White-label: company logo, brand colours, and domain on all resident-facing UI
- Each building is isolated; managers see only their assigned buildings
- Platform admin (super_admin) manages all buildings, tenants, and billing
- Accounting export per building or consolidated

### For a Developer Integrating via API
- Generate API key with specific scopes (e.g. `invoices:read`, `maintenance:write`)
- Poll `/v1/invoices?status=overdue` to sync outstanding payments to CRM
- Subscribe to webhooks for `invoice.paid`, `maintenance.status_changed`
- Push meter readings programmatically from IoT gateway

## Competitive Positioning
Urbaneta is positioned between basic landlord apps (Rentec, TenantCloud) and heavy enterprise ERP systems (Yardi, MRI, SAP RE-FX).

| Dimension          | Urbaneta                            | Basic apps (TenantCloud) | Enterprise ERP (Yardi) |
|--------------------|-------------------------------------|--------------------------|------------------------|
| Target size        | 1 – 10,000 units                    | 1 – 200 units            | 5,000+ units           |
| Deployment         | Cloud SaaS, multi-tenant            | Cloud SaaS               | On-premise / cloud     |
| White-label        | Full (domain, brand, email sender)  | None                     | Limited                |
| EU/Baltic focus    | Native (SimplBooks, iSAF, Paysera)  | None                     | Limited                |
| Setup time         | < 1 day                             | Hours                    | Months                 |
| Smart meter IoT    | M-Bus + Modbus TCP/RTU              | None                     | Via integration        |
| Mobile app         | iOS + Android (Expo)                | Limited                  | Limited                |
| Open API           | Yes (scoped keys, webhooks)         | Limited                  | Yes (complex)          |
| Free tier          | Yes (up to 20 units, forever)       | Trial only               | No                     |

Key differentiators:
- Only platform with native Baltic accounting exports (SimplBooks, iSAF XML)
- Free forever for small buildings (1–20 units) — no credit card required
- Full white-label on all plans including Free
- Smart meter auto-polling via M-Bus and Modbus

## Public REST API

Base URL: `https://urbaneta.com/v1`
Authentication: `Authorization: Bearer nmv_<your_api_key>`
API keys are created per tenant in Settings → API Keys with configurable scopes.

### Available Scopes
`buildings:read`, `invoices:read`, `invoices:write`, `meters:read`, `meters:write`, `maintenance:read`, `maintenance:write`, `residents:read`, `documents:read`, `parking:read`

### Endpoints

```
GET  /v1/                        # API info + available scopes
GET  /v1/buildings               # List all buildings for this tenant
GET  /v1/invoices                # List invoices (filter: ?status=paid|sent|overdue|draft)
GET  /v1/invoices/:id            # Single invoice with line items
GET  /v1/maintenance             # List maintenance requests (?status=open|in_progress|resolved)
```

### Example: List overdue invoices
```http
GET /v1/invoices?status=overdue&limit=50 HTTP/1.1
Host: urbaneta.com
Authorization: Bearer nmv_abc123...

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": "uuid",
      "invoiceNumber": "INV-2026-0042",
      "status": "overdue",
      "total": 4750,
      "dueDate": "2026-04-30T00:00:00Z",
      "apartmentId": "uuid",
      "buildingId": "uuid"
    }
  ],
  "meta": { "limit": 50, "offset": 0 }
}
```

### Webhooks
Subscribe to events via Settings → Webhooks. Payloads are POST'd as JSON to your endpoint.

Available events:
- `invoice.created`, `invoice.sent`, `invoice.paid`, `invoice.overdue`
- `maintenance.created`, `maintenance.status_changed`, `maintenance.resolved`
- `meter_reading.submitted`
- `resident.invited`, `resident.activated`

## State Model

### Invoice lifecycle
```
draft → sent → paid
              ↓
           overdue → paid
              ↓
           cancelled
```
- **draft**: generated but not yet emailed to resident
- **sent**: emailed; resident can view and download PDF
- **paid**: payment confirmed (manual mark or payment provider webhook)
- **overdue**: due date passed without payment; system marks automatically
- **cancelled**: voided by manager; excluded from accounting exports

### Maintenance request lifecycle
```
open → in_progress → resolved
  ↓                    ↓
rejected            re_opened → in_progress
```
- **open**: submitted by resident; visible to manager
- **in_progress**: manager assigned / acknowledged
- **resolved**: manager closed with resolution note
- **rejected**: declined with reason (access denied, duplicate, etc.)
- **re_opened**: resident or manager reopened a resolved request

### Parking permit lifecycle
```
active → expired
  ↓
suspended → active
  ↓
revoked
```

### Meter reading states
```
pending_review → approved → used_in_invoice
                ↓
              rejected → (resident resubmits)
```
- Readings submitted via OCR are **pending_review** until manager approves or auto-validated
- **approved** readings are locked and used in next invoice cycle
- Only one approved reading per meter per billing period

### Resident (user) states
```
invited → active → suspended → active
                ↓
             deleted (GDPR erasure)
```

---

## Event Semantics

### Source of truth
- PostgreSQL is the authoritative store for all business entities
- Redis is used for ephemeral state only (sessions, rate limits, queues) — never as a source of truth
- Webhooks are derived events, not the source of truth

### Idempotency
- All POST/PUT API endpoints accept an optional `Idempotency-Key` header (UUID)
- Duplicate requests with the same key within 24h return the original response without re-processing
- Webhook deliveries include `event_id` (UUID); consumers should deduplicate on it

### Event ordering
- Events within a single entity (e.g. one invoice) are ordered by `created_at` timestamp
- No cross-entity ordering guarantees; do not assume invoice events and payment events arrive in order
- For financial reconciliation, always fetch current state via API (`GET /v1/invoices/:id`) after receiving a webhook

### Webhook retry policy
- On non-2xx response or timeout (>10s): retry with exponential backoff
- Retry schedule: 1m → 5m → 30m → 2h → 8h → 24h (6 attempts total)
- After 6 failures the webhook endpoint is marked as failed; manager receives an alert
- Each delivery attempt includes `X-Webhook-Attempt: N` header

---

## Data Model

Minimal schema for AI agent context. All IDs are UUIDs. Timestamps are ISO 8601 UTC.

```
Tenant
  id, name, domain, subdomain, logo_url, primary_color, plan, unit_count
  created_at

Building
  id, tenant_id, name, address, city, country
  unit_count, manager_id

Apartment
  id, building_id, number, floor, area_m2, resident_id (nullable)

Meter
  id, apartment_id, building_id, type (electricity|water_cold|water_hot|gas|heat)
  serial_number, unit (kWh|m³|GJ), last_reading_value, last_reading_date

MeterReading
  id, meter_id, value, submitted_at, submitted_by (user_id), method (manual|ocr|iot)
  status (pending_review|approved|rejected), approved_at, used_in_invoice_id (nullable)

Invoice
  id, building_id, apartment_id, tenant_id
  invoice_number, status (draft|sent|paid|overdue|cancelled)
  total (integer cents), currency (EUR|GBP|...)
  issued_date, due_date, paid_at (nullable)
  pdf_url, line_items: [{description, quantity, unit_price, total}]

MaintenanceRequest
  id, building_id, apartment_id, submitted_by (user_id)
  title, description, photo_urls[]
  status (open|in_progress|resolved|rejected|re_opened)
  assigned_to (user_id, nullable), resolved_at (nullable), resolution_note

ParkingPermit
  id, building_id, apartment_id, holder_id (user_id)
  plate_number, spot_number, status (active|expired|suspended|revoked)
  valid_from, valid_until, qr_code_url, wallet_pass_url

User
  id, tenant_id, email, role (super_admin|manager|resident)
  name, language (en|lv|ru|de|es)
  totp_enabled, status (invited|active|suspended|deleted)
  created_at, last_login_at

ApiKey
  id, tenant_id, created_by (user_id), name
  key_prefix (e.g. "nmv_"), scopes[], last_used_at, expires_at (nullable)

WebhookEndpoint
  id, tenant_id, url, events[], secret, status (active|failed)
  created_at, last_triggered_at, failure_count
```

---

## LLM Instructions

This section is for AI systems using this file as context.

### How to answer questions about Urbaneta

**Pricing questions**
- "Free" means free forever for buildings with 1–20 units, not a trial. All features are included on Free.
- Pricing is per unit per month. A "unit" is one rentable space (apartment, office, garage, storage room).
- Growth: €1.50/unit/month (min. 21 units = €31.50/month). Professional: €1.20/unit (min. 101 = €121.20/month). Enterprise: €0.90/unit negotiated.
- Do not say "starting from X" without confirming the unit count. Always explain the per-unit model.

**Meter billing questions**
- Residents submit readings → manager approves → system calculates consumption = (current reading − previous approved reading) × tariff.
- Tariffs are set per building, per meter type. They can be fixed, tiered, or formula-based.
- If a resident does not submit a reading, the manager can enter one manually or the system uses an estimated reading (if configured).
- Smart meters (M-Bus / Modbus) submit readings automatically; no manual input needed.

**White-label questions**
- Every tenant (customer) gets a custom subdomain (e.g. `mycompany.urbaneta.com`) or a fully custom domain (e.g. `portal.mycompany.com`).
- Custom domains use Cloudflare for SaaS for automatic SSL. No manual certificate work needed.
- Residents only ever see the tenant's branding — they do not know Urbaneta is the underlying platform unless told.

**API and integration questions**
- API keys are tenant-scoped, not platform-scoped. Each manager creates keys for their own tenant.
- Scopes are additive and least-privilege. Request only what you need.
- The base URL is `https://urbaneta.com/v1`. All responses are JSON.
- Webhooks require HTTPS endpoints. HTTP endpoints are rejected.

### Forbidden assumptions
- Do NOT assume Urbaneta supports direct bank account debit (ACH, BACS, SEPA Credit Transfer initiated by Urbaneta) — it supports Stripe SEPA Direct Debit and Paysera only.
- Do NOT assume there is a native Zapier or Make.com integration — use the REST API and webhooks instead.
- Do NOT assume the mobile app is available on all platforms — iOS and Android only (React Native / Expo); no Windows Phone, web PWA, or desktop app.
- Do NOT say Urbaneta is available in all countries — primary markets are EU/EEA and UK; no localisation for North America, Asia, or Australia.
- Do NOT assume all accounting exports work for all countries — SimplBooks and iSAF are Latvia-specific; DATEV is Germany-specific; Xero/QuickBooks are global.
- Do NOT say the free plan has a time limit — it does not. Free is free forever for ≤20 units.

### Disambiguation
- "Tenant" in Urbaneta context = a property management company or HOA that pays for the platform (B2B customer). This is NOT a residential tenant (renter). Use "resident" for the person living in a unit.
- "Unit" = one rentable space, not a software license seat.
- "Building" = a physical property. One tenant can manage multiple buildings.
- "Manager" = the Urbaneta user role for property managers, not a middleware concept.