Skip to content

Technical Architecture Implementation

Purpose: Technical architecture specification for the Property Management System implementation.

Architecture Overview

graph TB
    subgraph "Frontend Layer"
        Web[Web App - Next.js 15 + React 19]
        Mobile[Mobile App - React Native]
        Admin[Admin Portal - React + TypeScript]
    end

    subgraph "API Gateway Layer"
        Gateway[API Gateway - YARP]
        Auth[Auth Service - Duende IdentityServer]
    end

    subgraph "Microservices Layer"
        Identity[Identity Service - Port 5001]
        User[User Service - Port 5002]
        Organization[Organization Service - Port 5003]
        Property[Property Service - Port 5004]
        Financial[Financial Service - Port 5005]
        Operations[Operations Service - Port 5006]
        Community[Community Service - Port 5007]
        Notifications[Notifications Service - Port 5008]
    end

    subgraph "Data Layer"
        PostgreSQL[(PostgreSQL - Single DB, 6 Schemas)]
        Redis[(Redis Cache)]
        MessageQueue[Message Queue - RabbitMQ]
    end

    Web --> Gateway
    Mobile --> Gateway
    Admin --> Gateway
    Gateway --> Auth
    Gateway --> Identity
    Gateway --> User
    Gateway --> Organization
    Gateway --> Property
    Gateway --> Financial
    Gateway --> Operations
    Gateway --> Community
    Gateway --> Notifications

    Identity --> PostgreSQL
    User --> PostgreSQL
    Organization --> PostgreSQL
    Property --> PostgreSQL
    Financial --> PostgreSQL
    Operations --> PostgreSQL
    Community --> PostgreSQL
    Notifications --> PostgreSQL

    Property --> MessageQueue
    Operations --> MessageQueue
    Community --> MessageQueue
    Notifications --> MessageQueue

System Architecture Principles

1. Microservices Architecture

  • Service Independence: Each service operates independently with its own database schema
  • Loose Coupling: Services communicate through well-defined APIs and message queues
  • Technology Consistency: All services use .NET 8 with Clean Architecture
  • Scalability: Services can be scaled independently based on demand

2. Event-Driven Architecture

  • Asynchronous Communication: Services communicate through events and messages
  • Loose Coupling: Services don't need to know about each other directly
  • Scalability: Easy to add new services that react to existing events
  • Reliability: Message queues provide reliability and retry mechanisms

3. Multi-Tenant Design

  • Data Isolation: Complete separation of data between organizations
  • Schema-Based Separation: Single database with multiple schemas for logical separation
  • Row-Level Security: Additional security layer for sensitive data
  • Customization: Each tenant can customize branding and features

Authentication & Authorization

Identity Service (Port 5001)

  • Technology: Duende IdentityServer 7
  • Authentication: OAuth 2.0, OpenID Connect, SAML, LDAP
  • Authorization: Role-based access control (RBAC) with fine-grained permissions
  • Security: JWT tokens, MFA, audit logging

JWT Token Structure

{
  "sub": "user-id",
  "org_id": "organization-id",
  "org_roles": ["PropertyManager", "Admin"],
  "permissions": ["property:read", "tenant:manage"],
  "tenant_profile_id": "tenant-id",
  "exp": 1516242622,
  "aud": "PropertyManagement"
}

🏢 Multi-Tenant Data Model

Database Schema Organization

PostgreSQL Database (PropertyManagementDB)
├── identity Schema (Identity Service)
│   ├── users, roles, user_roles, permissions
├── core Schema (User, Organization, Property Services)
│   ├── organizations, properties, units, user_profiles, tenants, leases
├── financial Schema (Financial Service)
│   ├── invoices, payments, expenses, budgets
├── operations Schema (Operations Service)
│   ├── work_orders, maintenance_requests, vendors, assets
├── communication Schema (Community, Notifications Services)
│   ├── messages, notifications, announcements, templates
└── shared Schema (Common Resources)
    ├── documents, settings, audit_logs

Data Isolation Strategy

  • Schema Separation: Each business domain has its own schema
  • Organization Context: All business data includes organization_id
  • Row-Level Security: PostgreSQL RLS policies enforce data isolation
  • Cross-Schema Queries: Views and functions provide cross-domain access

🏠 Property Management Architecture

Property Service (Port 5004)

  • Core Entities: Properties, Units, Tenants, Leases, Amenities
  • Business Logic: Property creation, unit management, tenant onboarding
  • Data Access: Entity Framework Core with repository pattern
  • Integration: Message queue for domain events

Key Data Models

erDiagram
    ORGANIZATION ||--o{ PROPERTY : owns
    PROPERTY ||--o{ UNIT : contains
    UNIT ||--o{ TENANT : occupied_by
    UNIT ||--o{ LEASE : has

    ORGANIZATION {
        UUID id PK
        VARCHAR name
        JSONB branding
        JSONB settings
    }

    PROPERTY {
        UUID id PK
        UUID organization_id FK
        VARCHAR name
        VARCHAR address
        VARCHAR property_type
        JSONB specifications
    }

    UNIT {
        UUID id PK
        UUID property_id FK
        VARCHAR unit_number
        VARCHAR unit_type
        DECIMAL square_feet
        VARCHAR status
    }

💰 Financial Management Architecture

Financial Service (Port 5005)

  • Core Entities: Invoices, Payments, Expenses, Budgets
  • Business Logic: Invoice generation, payment processing, expense tracking
  • External Integrations: Stripe/PayPal, accounting systems, banking APIs
  • Reporting: Financial analytics and budget management

Financial Operations

  • Invoice Generation: Automated invoice creation and management
  • Payment Processing: Multiple payment methods and gateway integration
  • Expense Management: Expense tracking and approval workflows
  • Budget Management: Budget planning and variance analysis

🔧 Operations Management Architecture

Operations Service (Port 5006)

  • Core Entities: Maintenance Requests, Work Orders, Vendors, Assets
  • Business Logic: Request management, work order tracking, vendor management
  • Integration: File storage, notifications, message queue
  • Quality Control: Work completion verification and customer satisfaction

Operations Workflow

sequenceDiagram
    participant Tenant
    participant Operations
    participant Vendor
    participant Notifications

    Tenant->>Operations: Submit Maintenance Request
    Operations->>Operations: Create Work Order
    Operations->>Vendor: Assign Work Order
    Vendor->>Operations: Update Work Progress
    Operations->>Notifications: Send Status Updates
    Operations->>Tenant: Complete Work Order

📢 Communication Architecture

Communication Service (Port 5007)

  • Core Entities: Messages, Notifications, Announcements, Templates
  • Business Logic: Message management, notification delivery, template management
  • Delivery Channels: Email (SendGrid/AWS SES), SMS (Twilio), Push notifications
  • Integration: In-app messaging and community features

Notification System

  • Multi-Channel Delivery: Email, SMS, push notifications, in-app
  • Template Management: Customizable message templates with variables
  • Scheduling: Configurable notification timing and frequency
  • Delivery Tracking: Analytics and delivery confirmation

🔌 API Design & Integration

RESTful API Standards

  • HTTP Methods: GET, POST, PUT, DELETE for CRUD operations
  • Status Codes: Appropriate HTTP status codes for responses
  • Error Handling: Consistent error response format
  • Versioning: API versioning for backward compatibility

Message Queue Integration

  • Technology: RabbitMQ for reliable message delivery
  • Event Types: Domain events, integration events, system events
  • Patterns: Producer-consumer pattern with dead letter queues
  • Reliability: Message persistence and retry mechanisms

🚀 Performance & Scalability

Caching Strategy

  • Application Cache: In-memory caching for frequently accessed data
  • Database Cache: Query result caching and connection pooling
  • Redis Cache: Distributed caching for session and shared data
  • CDN Integration: Static content delivery through CDN

Scalability Patterns

  • Horizontal Scaling: Load balancing across multiple service instances
  • Auto-scaling: Automatic scaling based on demand metrics
  • Service Discovery: Dynamic service registration and discovery
  • Health Checks: Service health monitoring and failover

🔒 Security Architecture

Security Layers

  • Network Security: HTTPS/TLS, VPN access, firewall rules
  • Application Security: Input validation, SQL injection protection, XSS protection
  • Data Security: Encryption at rest and in transit, key management
  • Compliance: GDPR compliance, data retention, audit logging

Authentication & Authorization

  • JWT Tokens: Stateless authentication with refresh token rotation
  • RBAC: Role-based access control with fine-grained permissions
  • Multi-Factor Authentication: Additional security layer
  • API Security: Rate limiting, API keys, scope-based access

📱 Frontend Architecture

Web Application (Next.js 15)

  • Technology: React 19, TypeScript, Tailwind CSS
  • Architecture: Server-side rendering with React Server Components
  • State Management: React Query for server state, Zustand for client state
  • Routing: Next.js App Router for navigation

Mobile Application (React Native)

  • Technology: React Native, TypeScript, Expo
  • State Management: Zustand for state management
  • Navigation: React Navigation 6
  • Offline Support: Local storage with sync capabilities

🐳 Infrastructure & Deployment

Containerization

  • Docker: Containerized services for consistency
  • Kubernetes: Container orchestration and scaling
  • Service Mesh: Istio for service-to-service communication
  • Load Balancing: Kubernetes load balancing and service discovery

CI/CD Pipeline

  • Source Control: Git with feature branch workflow
  • Build Automation: Automated build and testing
  • Security Scanning: Vulnerability and dependency scanning
  • Deployment: Automated deployment to environments

📊 Monitoring & Observability

Telemetry Stack

  • Application Insights: .NET application monitoring
  • OpenTelemetry: Distributed tracing and metrics collection
  • Prometheus: Metrics collection and storage
  • Grafana: Visualization and alerting dashboard

Key Metrics

  • Application Metrics: Response times, error rates, throughput
  • Business Metrics: Property occupancy, maintenance requests, payments
  • Infrastructure Metrics: CPU, memory, disk, network usage
  • Security Metrics: Failed logins, API abuse, security events

🏗️ Clean Architecture Implementation

Layer Structure

Clean Architecture Layers:
├── Web API Layer (Controllers, Middleware)
├── Application Layer (Use Cases, DTOs, Handlers)
├── Domain Layer (Entities, Value Objects, Services)
└── Infrastructure Layer (Repositories, External Services)

Service Communication

  • Synchronous: HTTP/REST for immediate consistency requirements
  • Asynchronous: Domain events via message bus for eventual consistency
  • Event-Driven: Loose coupling between services through events
  • API Gateway: Centralized entry point with authentication and routing

📋 Architecture Decision Records

ADR-001: Microservices Architecture

Status: Accepted Decision: Adopt microservices architecture with domain-driven design Consequences: Independent deployment, technology diversity, fault isolation

ADR-002: .NET 8 Technology Stack

Status: Accepted Decision: Use .NET 8 with ASP.NET Core for all backend services Consequences: Strong performance, rich ecosystem, good tooling

ADR-003: Single Database with Schema Separation

Status: Accepted Decision: Use single PostgreSQL database with schema-per-service approach Consequences: ACID transactions, simplified infrastructure, data consistency

ADR-004: Event-Driven Architecture

Status: Accepted Decision: Use domain events for asynchronous service communication Consequences: Loose coupling, scalability, resilience

ADR-005: API Gateway Pattern

Status: Accepted Decision: Implement API Gateway using YARP Consequences: Centralized configuration, security, monitoring

Next Steps