Residential Community Management in Comunidades Vecinos

Comunidades Vecinos is built around a strict multi-tenant model. Every resource in the platform — users, fees, receipts, financial movements, documents, and announcements — belongs to exactly one community (Comunidad). This isolation is enforced at the API level through the community ID that is embedded in each authenticated user’s JWT token; requests never need to pass a community identifier in the body because the backend extracts it from the token automatically.

The Comunidad Entity

The comunidades table stores the core identity information for each residential community:

Field	Column	Type	Description
`id`	`id_comunidad`	`Long` (auto)	Primary key
`nombre`	`nombre`	`String`	Display name of the community
`direccion`	`direccion`	`String`	Street address
`ciudad`	`ciudad`	`String`	City
`codPostal`	`cod_postal`	`String`	Postal code

API Endpoints

All community endpoints live under /api/comunidades. Only SUPER_ADMIN users can create or modify communities. ADMIN users can read their own community via GET /api/comunidades/{id}.

List all communities
Active-user summary
Get by ID
Create community
Update community

GET /api/comunidades
Authorization: Bearer <super_admin_token>

Returns the full list of Comunidad objects. Restricted to SUPER_ADMIN.

[
  {
    "id": 1,
    "nombre": "Comunidad Los Pinos",
    "direccion": "Calle de los Pinos, 12",
    "ciudad": "Madrid",
    "codPostal": "28001"
  },
  {
    "id": 2,
    "nombre": "Residencial El Olivo",
    "direccion": "Avenida del Olivo, 45",
    "ciudad": "Sevilla",
    "codPostal": "41001"
  }
]

GET /api/comunidades/activos
Authorization: Bearer <super_admin_token>

Returns a lightweight ActivoComunidad DTO for each community, including the count of currently active users (estado = true). This is the endpoint used by the ComunidadPage dashboard in the React frontend.

[
  {
    "id": 1,
    "nombre": "Comunidad Los Pinos",
    "codPostal": "28001",
    "usuarios": 14
  },
  {
    "id": 2,
    "nombre": "Residencial El Olivo",
    "codPostal": "41001",
    "usuarios": 8
  }
]

GET /api/comunidades/{id}
Authorization: Bearer <admin_or_super_admin_token>

Accessible by ADMIN and SUPER_ADMIN. Returns 404 if the community does not exist.

{
  "id": 1,
  "nombre": "Comunidad Los Pinos",
  "direccion": "Calle de los Pinos, 12",
  "ciudad": "Madrid",
  "codPostal": "28001"
}

POST /api/comunidades
Authorization: Bearer <super_admin_token>
Content-Type: application/json

Creates a new community. Restricted to SUPER_ADMIN.

{
  "nombre": "Comunidad Las Acacias",
  "direccion": "Calle de las Acacias, 3",
  "ciudad": "Valencia",
  "codPostal": "46001"
}

PUT /api/comunidades/{id}
Authorization: Bearer <super_admin_token>
Content-Type: application/json

Replaces all editable fields for the given community. Returns 404 if not found.

{
  "nombre": "Comunidad Las Acacias II",
  "direccion": "Calle de las Acacias, 3",
  "ciudad": "Valencia",
  "codPostal": "46002"
}

Multi-Tenant Isolation

JWT-embedded community ID

When a user logs in, the JWT issued by the backend contains both the user’s ID and their community ID as custom claims. Every subsequent request that requires community-scoped data reads these claims directly from the token — no idComunidad body field is required or accepted in most endpoints.

ADMIN community scope

An ADMIN user can only read and manage the single community they belong to. Attempting to access another community’s resources returns 403 Forbidden. Only SUPER_ADMIN can cross community boundaries.

Cascading ownership

All child resources — Usuario, Cuota, Recibo, Movimiento, Documento, and Publicacion — carry a mandatory foreign key to their parent Comunidad. There are no shared or global records below the community level.

Active-user count

The GET /api/comunidades/activos endpoint returns the ActivoComunidad DTO, which includes a usuarios field showing the number of active residents (those with estado = true). This is used by the SUPER_ADMIN dashboard to monitor community size at a glance.

Community deletion is not yet implemented in the current version. No DELETE /api/comunidades endpoint exists in the backend; communities cannot be removed through the API.

Getting Started

Core Features

Configuration

Residential Community Management in Comunidades Vecinos

The Comunidad Entity

API Endpoints

Multi-Tenant Isolation

JWT-embedded community ID

ADMIN community scope

Cascading ownership

Active-user count

Build docs developers (and LLMs) love

Getting Started

Core Features

Configuration

Documentation Index

​The Comunidad Entity

​API Endpoints

​Multi-Tenant Isolation

JWT-embedded community ID

ADMIN community scope

Cascading ownership

Active-user count

Build docs developers (and LLMs) love

The Comunidad Entity

API Endpoints

Multi-Tenant Isolation