PlanetPulse — Architecture and Naming Conventions

1. Architecture Overview

PlanetPulse is organized into three main parts: the frontend, the backend, and the database. Each part has a specific responsibility to ensure separation of concerns, maintainability, and scalability.

1.1 Project Structure

planetpulse/
├── backend/
├── database/
├── frontend/
├── README.md
└── .gitignore

• Frontend: Displays the user interface and handles user interactions.
• Backend: Processes requests, applies business rules, and exposes the REST API.
• Database: Stores and manages application data.

2. Frontend Architecture

The frontend is developed using native JavaScript, JavaScript modules, Web Components, HTML, CSS, and Bootstrap.

It follows a Multi-Page Application (MPA) approach, with separate HTML pages for different screens.

frontend/
├── index.html
├── pages/
│   ├── countries-page.html
│   ├── countries-page.js
│   └── ...
├── js/
│   ├── components/
│   │   └── NavBar.js
│   └── services/
│       └── countries-services.js
├── css/
└── assets/

Responsibilities

• pages/: Contains the HTML pages and their associated JavaScript logic.
• js/components/: Contains reusable interface components implemented with Web Components.
• js/services/: Handles communication with the backend API using fetch().
• css/: Contains application-specific styles, in addition to Bootstrap.
• assets/: Stores static resources such as images, logos, and icons.

3. Backend Architecture

The backend uses Java, Spring Boot, and Maven. The application follows a layered architecture organized by business domain.

backend/src/main/java/com/planetpulse/
├── PlanetPulseApplication.java
├── country/
│   ├── Country.java
│   ├── CountryController.java
│   ├── CountryService.java
│   ├── CountryRepository.java
│   └── dto/
├── note/
├── indicator/
├── target/
├── report/
└── common/

3.1 Application Entry Point

PlanetPulseApplication.java is the main entry point of the Spring Boot application.

3.2 Domain Packages

Each domain has its own package to group related classes and responsibilities.

• country/: Manages country-related operations.
• note/: Manages environmental monitoring notes.
• indicator/: Handles environmental indicators.
• target/: Manages environmental targets.
• report/: Handles report generation, including integration with an AI service.
• common/: Contains shared components, such as custom exceptions and global error handling.

3.3 Backend Layers

Within each domain, classes are organized according to their responsibilities.

Layer	Responsibility	Example
Controller	Receives HTTP requests and returns HTTP responses	CountryController
Service	Implements business logic	CountryService
Repository	Handles data access	CountryRepository
Entity / Model	Represents domain data	Country
DTO	Transfers data between application layers or through the API	CountryDTO

The typical request flow is:

Controller → Service → Repository → Database

The response follows the reverse path.

3.4 Resources and Configuration

The src/main/resources/ directory contains application configuration files.

• application.properties: Default application configuration.
• application-staging.properties: Configuration specific to the staging environment. Environment-specific configuration should be managed carefully to avoid exposing credentials or sensitive information.

4. Database Architecture

The database/ directory contains SQL scripts used to initialize and configure the database.

database/
├── common/
│   ├── 01-schema.sql
│   └── 02-roles.sql
├── countries/
│   ├── 01-schema.sql
│   └── 02-roles.sql
└── README.md

Responsibilities

• common/: Contains shared database objects and configuration.
• countries/: Contains SQL scripts specific to the country domain.
• README.md: Explains how to execute the database scripts. The schema scripts define database structures and constraints. The role scripts configure database users and permissions.

Database scripts must be executed in the documented order to ensure that dependencies are respected.

5. Naming Conventions

The following conventions ensure consistency across the PlanetPulse codebase.

5.1 General Rules

• Use English for identifiers.
• Choose clear and descriptive names.
• Use one consistent naming convention for each type of element.
• Avoid unnecessary abbreviations.
• Keep names consistent with the corresponding business domain.

5.2 Java and Spring Boot

Element	Convention	Example
Packages	lowercase	com.planetpulse.country
Classes	PascalCase	CountryService
Interfaces	PascalCase	CountryRepository
Methods	camelCase	findAllCountries()
Variables	camelCase	countryName
Constants	UPPER_SNAKE_CASE	MAX_RESULTS
DTO classes	PascalCase with DTO suffix	CountryDTO
Exceptions	PascalCase with Exception suffix	CountryNotFoundException
Test classes	Class name followed by Test	CountryServiceTest

Examples:

• Country.java
• CountryController.java
• CountryService.java
• CountryRepository.java
• CountryDTO.java Class names should describe their purpose, and methods should use verbs that express the action performed.

5.3 JavaScript

Element	Convention	Example
Variables	camelCase	countryName
Functions	camelCase	getCountries()
Classes	PascalCase	CountryService
Web Components	PascalCase	NavBar
Constants	UPPER_SNAKE_CASE	API_BASE_URL
HTML files	kebab-case	countries-page.html
Page JavaScript files	kebab-case	countries-page.js
Service files	kebab-case	countries-services.js
CSS files	kebab-case	countries-list.css

JavaScript modules should use clear, descriptive names that reflect their responsibilities.

5.4 HTML and CSS

Element	Convention	Example
HTML files	kebab-case	countries-page.html
CSS files	kebab-case	countries-page.css
CSS classes	kebab-case	country-card
HTML IDs	kebab-case	country-list

CSS class names should describe the component or element they represent rather than its visual appearance alone.

5.5 SQL and Database Objects

Element	Convention	Example
Tables	snake_case, plural	countries
Columns	snake_case	country_name
Primary keys	pk_ prefix	pk_countries
Foreign keys	fk_ prefix	fk_notes_countries
Indexes	idx_ prefix	idx_countries_name
SQL scripts	Numeric prefix and kebab-case or descriptive name	01-schema.sql

Database naming must remain consistent with the existing schema and its constraints.

5.6 Directory and File Names

• Use lowercase names for directories.
• Use descriptive names based on the feature or technical responsibility.
• Use kebab-case for frontend files and page names.
• Use the standard Java package structure for backend code.
• Keep database scripts grouped by domain or shared responsibility.

6. Design Principles

PlanetPulse follows these architectural principles:

• Separation of concerns: Each layer has a clearly defined responsibility.
• Modularity: Features are grouped into domain-specific packages.
• Reusability: Shared frontend components and backend utilities should be reused when appropriate.
• Maintainability: Consistent structure and naming make the code easier to understand and modify.
• Security: Credentials and sensitive configuration must not be committed to the repository.
• Consistency: All contributors should follow the same architectural and naming conventions.

7. Team Agreement

All contributors should follow the architecture and naming conventions documented on this page.

Any proposed changes to the project structure or naming rules should be discussed and agreed upon by the team before being applied consistently across the codebase.