Documentation Index
Fetch the complete documentation index at: https://mintlify.com/GuillermoNavarro/Proyecto_comunidades/llms.txt
Use this file to discover all available pages before exploring further.
Comunidades Vecinos uses MariaDB as its primary data store. The Spring Data JPA layer manages the schema automatically via Hibernate’s ddl-auto=update strategy, so no manual migration scripts are required for the initial setup. You only need to create the database and a dedicated user before starting the backend for the first time.
Requirements
- MariaDB 10.6+ (recommended) or MySQL 8+
- A database user with
ALL PRIVILEGES on the comunidad_vecinos schema
- The database server must be reachable from the host where the backend runs (default:
localhost:3306)
Creating the Database and User
Connect to your MariaDB server as the root user (or any user with CREATE and GRANT privileges) and run the following statements:
CREATE DATABASE comunidad_vecinos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'comunidad_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON comunidad_vecinos.* TO 'comunidad_user'@'localhost';
FLUSH PRIVILEGES;
Use utf8mb4 rather than utf8 to ensure full Unicode support, including emoji and supplementary characters that may appear in community notices or comments.
DB_USER=comunidad_user and DB_PASSWORD=your_password in your environment before starting the backend. Hibernate will create all tables automatically on the first run.
Schema Overview
The tables below are created and maintained automatically by Spring Data JPA. The descriptions reflect the real JPA entities in the application.
comunidades
Represents a residential homeowners community (the top-level tenant of the application).
| Column | Type | Description |
|---|
id_comunidad | BIGINT PK | Auto-generated surrogate key. |
nombre | VARCHAR | Community display name. |
direccion | VARCHAR | Street address. |
ciudad | VARCHAR | City. |
cod_postal | VARCHAR | Postal code. |
usuarios
Stores all user accounts — residents, administrators, and the super-admin.
| Column | Type | Description |
|---|
id_usuario | BIGINT PK | Auto-generated surrogate key. |
dni | VARCHAR | Spanish national identity number (unique per community). |
nombre | VARCHAR | First name. |
apellidos | VARCHAR | Surname(s). |
email | VARCHAR | Login email address (used as the JWT subject). |
puerta | VARCHAR | Apartment or door identifier within the building. |
telefono | VARCHAR | Contact phone number. |
password | VARCHAR | BCrypt-hashed password. |
rol | VARCHAR | Role: SUPER_ADMIN, ADMIN, or VECINO. |
id_comunidad | BIGINT FK → comunidades | The community this user belongs to. |
coeficiente | DECIMAL | Ownership coefficient (participation quota). |
estado | BOOLEAN | Whether the account is active. |
cambiar_pass | BOOLEAN | Flags that the user must change their password on next login. |
cuotas
Represents a fee or levy issued to all residents of a community.
| Column | Type | Description |
|---|
id_cuota | BIGINT PK | Auto-generated surrogate key. |
nombre | VARCHAR | Fee name or description. |
fecha_emision | DATE | Issue date. |
fecha_vencimiento | DATE | Due date. |
importe_total | DECIMAL | Total amount for the community. |
tipo | VARCHAR | Fee type (e.g., ordinary, extraordinary). |
id_comunidad | BIGINT FK → comunidades | The community this fee belongs to. |
recibos
An individual payment receipt — one per resident per fee.
| Column | Type | Description |
|---|
id_recibo | BIGINT PK | Auto-generated surrogate key. |
id_cuota | BIGINT FK → cuotas | The parent fee. |
id_comunidad | BIGINT FK → comunidades | Denormalized community reference. |
id_usuario | BIGINT FK → usuarios | The resident this receipt belongs to. |
importe | DECIMAL | Amount owed by this resident (total × coefficient). |
estado | VARCHAR | Payment status (e.g., PENDIENTE, PAGADO). |
movimientos
A general ledger of financial movements for a community (income, expenses, and fee payments).
| Column | Type | Description |
|---|
id_movimiento | BIGINT PK | Auto-generated surrogate key. |
nombre | VARCHAR | Description of the movement. |
id_comunidad | BIGINT FK → comunidades | The community this movement belongs to. |
id_usuario | BIGINT FK → usuarios | Associated resident, if applicable (nullable). |
fecha | DATE | Date of the movement. |
importe | DECIMAL | Monetary amount. |
tipo | VARCHAR | Movement type (e.g., INGRESO, GASTO). |
id_recibo | BIGINT FK → recibos | Linked receipt, if the movement is a fee payment (nullable). |
publicaciones
Community announcements or news posts created by administrators.
| Column | Type | Description |
|---|
id_publicacion | BIGINT PK | Auto-generated surrogate key. |
titulo | VARCHAR | Post title. |
contenido | TEXT | Body text of the announcement. |
fecha | DATETIME | Publication timestamp. |
id_comunidad | BIGINT FK → comunidades | The community this post belongs to. |
id_usuario | BIGINT FK → usuarios | Author. |
documentos
PDF and other file attachments uploaded to the community document repository.
| Column | Type | Description |
|---|
id_documento | BIGINT PK | Auto-generated surrogate key. |
nombre | VARCHAR | Document display name. |
ruta | VARCHAR | Absolute filesystem path (under app.upload.dir). |
fecha | DATETIME | Upload timestamp. |
id_comunidad | BIGINT FK → comunidades | The community this document belongs to. |
comentarios
Comments left by residents on community publications.
| Column | Type | Description |
|---|
id_comentario | BIGINT PK | Auto-generated surrogate key. |
contenido | TEXT | Comment body. |
fecha | DATETIME | Creation timestamp. |
id_publicacion | BIGINT FK → publicaciones | The post being commented on. |
id_usuario | BIGINT FK → usuarios | Author. |
Schema Management
The schema is created and kept up to date automatically by Spring Data JPA using spring.jpa.hibernate.ddl-auto=update. You do not need to run any CREATE TABLE scripts manually — starting the backend against an empty comunidad_vecinos database is sufficient.
Never set spring.jpa.hibernate.ddl-auto=create-drop in a production environment. This strategy drops the entire schema on every application shutdown and recreates it on startup, permanently destroying all data.
Seeding the First Admin User
There is no automated seed script. After the backend has started once (and Hibernate has created all the tables), you must insert the first SUPER_ADMIN user directly into the database. This account can then create communities and additional administrators through the application UI.
Passwords are hashed with BCrypt. Generate a hash before running the insert:
# Requires Apache httpd-tools (htpasswd)
htpasswd -bnBC 10 "" yourpassword | tr -d ':\n'
-- 1. Create the platform-level pseudo-community for the super-admin
INSERT INTO comunidades (nombre, direccion, ciudad, cod_postal)
VALUES ('Plataforma', 'Admin', 'Admin', '00000');
-- 2. Insert the SUPER_ADMIN user (id_comunidad = 1 from the row above)
INSERT INTO usuarios (dni, nombre, apellidos, email, password, rol, id_comunidad, coeficiente, estado, cambiar_pass)
VALUES (
'00000000A',
'Admin',
'Sistema',
'[email protected]',
'$2a$10$...your_bcrypt_hash_here...',
'SUPER_ADMIN',
1,
1.0,
true,
false
);
You can also generate a BCrypt hash online (search for “BCrypt generator”) or programmatically via Spring’s BCryptPasswordEncoder: new BCryptPasswordEncoder().encode("yourpassword"). The cost factor used by the application is the BCrypt default (10 rounds).