Skip to main content

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.

This guide walks you through cloning the repository, wiring up a local MariaDB database, starting the backend API on port 8081, and launching the React frontend — all the way to your first successful login as the platform operator (SUPER_ADMIN). By the end you will have a fully working local environment ready for development or evaluation.

​
Prerequisites

Before you begin, make sure the following tools are installed and available on your PATH:
RequirementMinimum versionNotes
Java JDK21Required by Spring Boot 4. OpenJDK or any compatible distribution.
Apache Maven3.9+The project includes a Maven Wrapper (mvnw), so a global install is optional.
Node.js18+LTS recommended. npm is bundled with Node.
MariaDB or MySQL10.6+ / 8.0+A running instance accessible on localhost:3306.
1

Clone the repository

Clone the project from its source and enter the root directory.
git clone https://github.com/GuillermoNavarro/Proyecto_comunidades.git
cd Proyecto_comunidades
The repository contains two sub-projects:
Proyecto_comunidades/
├── backend/    # Spring Boot 4 Maven project
└── frontend/   # React 19 Vite project
2

Set up the database

Connect to your MariaDB or MySQL server and create the application schema. Spring Boot’s ddl-auto=update will create all tables automatically on first startup — you only need to create the empty database.
CREATE DATABASE IF NOT EXISTS comunidad_vecinos
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;
Verify the database was created:
SHOW DATABASES LIKE 'comunidad_vecinos';
The application connects to localhost:3306 by default. If your MariaDB instance runs on a different host or port, update spring.datasource.url in backend/src/main/resources/application.properties accordingly.
3

Configure and run the backend

The backend reads three secrets from environment variables to avoid storing credentials in source control. Set them in your shell before running the application:
export DB_USER=your_db_username
export DB_PASSWORD=your_db_password
export JWT_SECRET=a_long_random_secret_string_at_least_32_chars
Then start the Spring Boot application from the backend/ directory:
cd backend
./mvnw spring-boot:run
On Windows use mvnw.cmd spring-boot:run. Maven will download dependencies on the first run. Once the application is ready you will see output similar to:
Started ComunidadBackendApplication in 4.3 seconds (process running for 5.0)
The backend listens on port 8081. The full application.properties configuration is shown below for reference:
spring.application.name=comunidad-backend
server.port=8081

spring.datasource.url=jdbc:mariadb://localhost:3306/comunidad_vecinos
spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASSWORD}
spring.datasource.driver-class-name=org.mariadb.jdbc.Driver
spring.jpa.database-platform=org.hibernate.dialect.MariaDBDialect
spring.jpa.hibernate.ddl-auto=update

jwt.secret=${JWT_SECRET}

app.upload.dir=/var/www/comunidades/documents/
app.upload.images.dir=/var/www/comunidades/images/

spring.servlet.multipart.max-file-size=15MB

spring.mail.host=localhost
spring.mail.port=1025
The file upload directories (/var/www/comunidades/documents/ and /var/www/comunidades/images/) must exist and be writable by the process user. Create them before uploading any files, or change the paths in application.properties to a directory that already exists on your system.
Explore all available REST endpoints interactively at http://localhost:8081/swagger-ui/index.html — no authentication required to browse the Swagger UI.
4

Configure and run the frontend

Open a new terminal, navigate to the frontend/ directory, and install dependencies:
cd frontend
npm install
The Vite dev server is configured to proxy API requests to the backend so that both services can run simultaneously without CORS issues. Verify that your vite.config.js contains a proxy entry pointing to the backend port:
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8081',
        changeOrigin: true,
      },
    },
  },
})
Start the development server:
npm run dev
Vite will print the local URL — typically http://localhost:5173. Open it in your browser.
5

Log in and bootstrap the platform

With both services running, open http://localhost:5173 in your browser. You will see the public landing page with a login form.First-time setup order:
  1. Log in as SUPER_ADMIN using the credentials that were seeded into the database (or that you inserted manually into the usuarios table). The SUPER_ADMIN role is the platform operator and has global access.
  2. Create the first community — navigate to Comunidades (/comunidades) and click Nueva Comunidad. Fill in the nombre, direccion, ciudad, and codPostal fields.
  3. Add an ADMIN user — navigate to Gestión de Usuarios (/usuarios) and create a new user assigned to the community you just created, with the ADMIN role. This user will act as the community president or treasurer.
Every newly created user has cambiarPass = true by default. When that user logs in for the first time, the backend issues a JWT with the ROLE_PRE_AUTH authority, and the frontend forces a password-change screen before granting access to the rest of the application.
Once the ADMIN user has changed their password and logged in, they can invite residents (USER role), create fee quotas, manage documents, and post announcements — all scoped to their own community.

​
What’s next?

Architecture

Understand how the backend layers, frontend pages, data model, and security filter chain fit together.

Swagger UI

Browse and test every REST endpoint with the built-in interactive API reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us