Contract Violations

Overview

The contract violations module allows you to document and track cases of non-compliance with Lease Agreement terms. Each violation can be linked to specific contract clauses and supported with photo evidence.

Severity Levels

The system uses 4 severity levels to classify violations:

Workflow

Typical violation documentation process:

Permissions

Different users have different permissions:

Automatic Overdue Payment Control

The system automatically detects late payments and creates contract violations. A daily cron job (app:payments:check-overdue) runs at 05:00 UTC and checks the previous month's payments.

How it works

1. For each property with an active contract, the system reads RENT_PAYMENT_DAY and UTILITIES_PAYMENT_DAY + grace period from the contract blocks
2. Finds payments made after the deadline (charge date + grace period)
3. Groups overdue payments by deadline date
4. Creates a ContractViolation with auto-generated description in the tenant's language
5. Links overdue payments to the violation via violation_overdue_payments junction table

Severity rules

Utilities overdue always gets severity 5 (medium).

If a contract does not have RENT_PAYMENT_DAY or UTILITIES_PAYMENT_DAY blocks — no violation is created for that type.

Payment linking

Each violation can be linked to one or more overdue payments. One payment can be linked to at most one violation (UNIQUE constraint). Payments can also be linked manually when creating or editing a violation.

REST API

REST API for integration with external systems:

Service layer note

GET    /api/v1/properties/{id}/violations           - List violations
POST   /api/v1/properties/{id}/violations           - Create violation
GET    /api/v1/properties/{id}/violations/{vid}     - Violation details
PUT    /api/v1/properties/{id}/violations/{vid}     - Update violation
DELETE /api/v1/properties/{id}/violations/{vid}     - Delete violation
POST   /api/v1/properties/{id}/violations/{vid}/documents      - Attach document
DELETE /api/v1/properties/{id}/violations/{vid}/documents/{did} - Detach document

GET    /api/v1/properties/{id}/violations/{vid}/overdue-payments          - List linked overdue payments
POST   /api/v1/properties/{id}/violations/{vid}/overdue-payments          - Link payments (payment_ids[])
DELETE /api/v1/properties/{id}/violations/{vid}/overdue-payments/{payId}  - Unlink payment
GET    /api/v1/properties/{id}/overdue-payments                          - List unlinked overdue payments

Example Response

{
  "data": [
    {
      "id": 1,
      "property_id": 5,
      "contract_id": 12,
      "violation_date": "2026-01-10",
      "severity": 7,
      "severity_level": "high",
      "description": "Unauthorized subletting of the property to third party",
      "violator": {
        "id": 15,
        "name": "John Tenant"
      },
      "created_by": {
        "id": 8,
        "name": "Owner Name"
      },
      "documents_count": 2,
      "blocks": [
        {
          "id": 5,
          "code": "SUBLETTING",
          "name": "Subletting Prohibition"
        }
      ],
      "created_at": "2026-01-10T14:30:00+00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "totalPages": 1
}

Swagger / OpenAPI

Full API documentation is available at /api/v1/doc