Коммит f55854d9 создал по автору Radch-enko's avatar Radch-enko
Просмотр файлов

docs: add READMEs for core and build-logic modules 

- Added detailed documentation for `core` modules: Data, Domain, and Repository, covering architecture, key components, and development guidelines.
- Created a README for the `build-logic` module, documenting Gradle convention plugins and their use cases.
- Updated `backend` README to include feature-specific links and reorganized sections for clarity.
- Improved root README with additional references to new documentation files.
владелец 93d83bec
Скрыть пробелы
Построчно Рядом
README.md
Просмотр файла @ f55854d9
...@@ -70,6 +70,7 @@ effective-office/ ...@@ -70,6 +70,7 @@ effective-office/
For detailed documentation: For detailed documentation:
- [Backend Documentation](./backend/README.md) - [Backend Documentation](./backend/README.md)
- [Client Documentation](./clients/README.md) - [Client Documentation](./clients/README.md)
- [Build Logic Documentation](./build-logic/README.md)
- [Calendar Integration Documentation](docs/CALENDAR_INTEGRATION.md) - [Calendar Integration Documentation](docs/CALENDAR_INTEGRATION.md)
## Development Tools ## Development Tools
......
backend/README.md
Просмотр файла @ f55854d9
...@@ -23,6 +23,13 @@ backend/ ...@@ -23,6 +23,13 @@ backend/
├── docs/ # API documentation ├── docs/ # API documentation
└── scripts/ # Backend-specific utility scripts └── scripts/ # Backend-specific utility scripts
``` ```
For detailed documentation:
- [Feature authorization](./backend/feature/authorization/README.md)
- [Feature booking](./backend/feature/booking/README.md)
- [Feature calendar-subscription](./backend/feature/calendar-subscription/README.md)
- [Feature notifications](./backend/feature/notifications/README.md)
- [Feature user](./backend/feature/user/README.md)
- [Feature workspace](./backend/feature/workspace/README.md)
## Technology Stack ## Technology Stack
...@@ -108,7 +115,6 @@ The database schema includes tables for: ...@@ -108,7 +115,6 @@ The database schema includes tables for:
``` ```
This will use the configuration from `application-local.yml`. This will use the configuration from `application-local.yml`.
## Deployment ## Deployment
### Using Docker ### Using Docker
The backend can be deployed using Docker: The backend can be deployed using Docker:
......
backend/app/README.md 0 → 100644
Просмотр файла @ f55854d9
# App Module
## Overview
The App Module is the main application module that ties together all components of the Effective Office backend. It serves as the entry point for the application, configures the Spring Boot environment, and orchestrates the integration of all other modules.
## Features
- Application bootstrapping and initialization
- Module integration and coordination
- Global configuration management
- API endpoint exposure
- Security configuration
- Error handling and exception management
## Architecture
The module follows a standard Spring Boot application structure:
```
app/
├── src/
│ └── main/
│ ├── kotlin/
│ │ └── band/
│ │ └── effective/
│ │ └── office/
│ │ └── backend/
│ │ └── app/
│ │ ├── EffectiveOfficeApplication.kt # Main application class
│ │ ├── config/ # Application-wide configuration
│ │ │ ├── SecurityConfig.kt # Security configuration
│ │ │ ├── WebConfig.kt # Web configuration
│ │ │ └── SwaggerConfig.kt # API documentation configuration
│ │ └── exception/ # Global exception handling
│ └── resources/
│ ├── application.yml # Main application properties
│ ├── application-dev.yml # Development environment properties
│ ├── application-prod.yml # Production environment properties
│ └── application-local.yml # Local development properties
```
## Key Components
### Main Application
- **EffectiveOfficeApplication**: The main Spring Boot application class with the `@SpringBootApplication` annotation that serves as the entry point for the application.
### Configuration
- **SecurityConfig**: Configures Spring Security for authentication and authorization
- **WebConfig**: Configures web-related settings like CORS, content negotiation, etc.
- **SwaggerConfig**: Configures Swagger/OpenAPI documentation
### Exception Handling
- **GlobalExceptionHandler**: Provides centralized exception handling for the entire application
## Integration
The App Module integrates all other modules of the Effective Office backend:
- **Core Modules**:
- Data Module: For data access and persistence
- Domain Module: For business logic and domain models
- Repository Module: For database access
- **Feature Modules**:
- Authorization Module: For user authentication and authorization
- Booking Module: For resource booking management
- Calendar Subscription Module: For calendar integration
- Notifications Module: For user notifications
- User Module: For user management
- Workspace Module: For workspace and office space management
## Configuration
The module provides environment-specific configurations:
- **application.yml**: Default configuration properties
- **application-local.yml**: Local development configuration
## Usage
To run the application:
```bash
./gradlew :backend:app:bootRun
```
To run with a specific profile:
```bash
./gradlew :backend:app:bootRun --args='--spring.profiles.active=local'
```
To build the application:
```bash
./gradlew :backend:app:build
```
## Development
When extending this module:
1. Maintain clear separation of concerns
2. Add new configurations in the appropriate configuration classes
3. Ensure proper integration with other modules
4. Follow Spring Boot best practices for application structure
\ No newline at end of file
backend/core/data/README.md 0 → 100644
Просмотр файла @ f55854d9
# Data Module
## Overview
The Data Module provides common data structures and data transfer objects (DTOs) used across the Effective Office backend. It defines standardized formats for data exchange between different parts of the application.
## Features
- Standardized error response format
- Common data transfer objects
- Shared data structures
## Architecture
The module follows a simple structure:
```
data/
├── src/
│ └── main/
│ └── kotlin/
│ └── band/
│ └── effective/
│ └── office/
│ └── backend/
│ └── core/
│ └── data/
│ └── ErrorDto.kt # Error data transfer object
```
## Key Components
### Data Transfer Objects
- **ErrorDto**: A standardized error response format used across all services
- Contains a message describing the error
- Includes an error code for categorization
## Integration
The Data Module is used by:
- API controllers for standardized error responses
- Service layers for data exchange
- Other modules that need to use common data structures
## Usage Examples
### Error Response Example
```kotlin
// Creating a standard error response
val errorResponse = ErrorDto(
message = "Resource not found",
code = 404
)
// Using in a controller
@ExceptionHandler(ResourceNotFoundException::class)
fun handleResourceNotFoundException(ex: ResourceNotFoundException): ResponseEntity<ErrorDto> {
val errorDto = ErrorDto(
message = ex.message ?: "Resource not found",
code = 404
)
return ResponseEntity(errorDto, HttpStatus.NOT_FOUND)
}
```
## Configuration
The module has minimal configuration requirements as it primarily consists of data structures.
## Development
When extending this module:
1. Follow the established patterns for creating DTOs
2. Ensure backward compatibility when modifying existing DTOs
3. Add proper documentation for new data structures
\ No newline at end of file
backend/core/domain/README.md 0 → 100644
Просмотр файла @ f55854d9
# Domain Module
## Overview
The Domain Module defines the core business entities, interfaces, and services for the Effective Office backend. It encapsulates the business logic and rules of the application, independent of specific implementations or external dependencies.
## Features
- Core domain models representing business entities
- Service interfaces defining business operations
- Business logic and validation rules
## Architecture
The module is organized into model and service packages:
```
domain/
├── src/
│ └── main/
│ └── kotlin/
│ └── band/
│ └── effective/
│ └── office/
│ └── backend/
│ └── core/
│ └── domain/
│ ├── model/ # Domain entities
│ │ ├── CalendarId.kt
│ │ ├── User.kt
│ │ ├── Utility.kt
│ │ ├── Workspace.kt
│ │ └── WorkspaceZone.kt
│ └── service/ # Domain services
│ ├── UserDomainService.kt
│ └── WorkspaceDomainService.kt
```
## Key Components
### Domain Models
- **User**: Represents a user in the system with properties like username, email, name, etc.
- **Workspace**: Represents a workspace or office space
- **WorkspaceZone**: Represents a zone within a workspace
- **Utility**: Represents utilities available in workspaces
- **CalendarId**: Represents a calendar identifier linked to a workspace
### Domain Services
- **UserDomainService**: Defines operations for user management (find, create)
- **WorkspaceDomainService**: Defines operations for workspace management
## Validation
The domain models include validation annotations to ensure data integrity:
- Required fields validation
- String length constraints
- Email format validation
## Integration
The Domain Module is used by:
- Feature modules that implement business logic
- Repository implementations that persist domain entities
- API controllers that expose domain operations
## Usage Examples
### Working with Domain Models
```kotlin
// Creating a new user
val user = User(
username = "johndoe",
email = "john.doe@example.com",
firstName = "John",
lastName = "Doe",
role = "USER"
)
// Using domain services
class UserServiceImpl(private val userRepository: UserRepository) : UserDomainService {
override fun findByUsername(username: String): User? {
return userRepository.findByUsername(username)
}
override fun createUser(user: User): User {
// Business logic for user creation
return userRepository.save(user)
}
}
```
## Development
When extending this module:
1. Keep domain models focused on business concepts, not technical details
2. Ensure domain services define clear contracts for business operations
3. Maintain separation between domain logic and implementation details
4. Add proper validation to ensure data integrity
\ No newline at end of file
backend/core/repository/README.md 0 → 100644
Просмотр файла @ f55854d9
# Repository Module
## Overview
The Repository Module provides database access and persistence functionality for the Effective Office backend. It manages database connections, migrations, and implements data access patterns for storing and retrieving domain entities.
## Features
- Database configuration and connection management
- Database schema definition and migrations
- Data access layer for domain entities
## Architecture
The module is organized into configuration and database migration resources:
```
repository/
├── src/
│ └── main/
│ ├── kotlin/
│ │ └── band/
│ │ └── effective/
│ │ └── office/
│ │ └── backend/
│ │ └── core/
│ │ └── repository/
│ │ └── config/
│ │ └── DatabaseConfig.kt # Database configuration
│ └── resources/
│ ├── application-repository.yml # Repository-specific configuration
│ └── db/
│ └── migration/
│ └── V1__create_tables.sql # Database schema migration
```
## Key Components
### Configuration
- **DatabaseConfig**: Spring configuration class that enables JPA repositories and transaction management
### Database Schema
The module defines the following database tables:
- **workspace_zones**: Stores workspace zone information
- **users**: Stores user information
- **workspaces**: Stores workspace information
- **utilities**: Stores utilities information
- **workspace_utilities**: Links workspaces and utilities
- **api_keys**: Stores API keys for authentication
- **calendar_ids**: Stores calendar IDs linked to workspaces
- **calendar_channels**: Stores Google Calendar notification channels
## Database Migrations
The module uses Flyway for database migrations:
- **V1__create_tables.sql**: Creates the initial database schema with all necessary tables, indexes, and constraints
### How to Implement Migrations
#### Migration Naming Convention
Flyway uses a specific naming convention for migration files:
```
V{version}__{description}.sql
```
- `{version}`: A version number (e.g., 1, 2, 3.1, 4.5.7)
- `{description}`: A description with words separated by underscores
Examples:
- `V1__create_tables.sql`
- `V2__add_user_preferences.sql`
- `V3__alter_workspace_table.sql`
#### Creating a New Migration
1. **Determine the next version number**: Look at the existing migrations in `src/main/resources/db/migration/` and increment the highest version number.
2. **Create a new SQL file** in the `src/main/resources/db/migration/` directory following the naming convention.
3. **Write your SQL statements** in the file. Include:
- Clear comments explaining the purpose of each change
- Table creation statements with appropriate constraints
- Index creation for frequently queried columns
- Comments on tables and columns for documentation
- Any necessary data migrations
4. **Test your migration** by running the application with the new migration file in place.
#### Best Practices
1. **Make migrations idempotent** when possible (can be run multiple times without causing errors)
2. **Use explicit naming** for constraints, indexes, and foreign keys
3. **Include comments** in your SQL to explain complex changes
4. **Keep migrations focused** on a specific change or related set of changes
5. **Never modify existing migration files** that have been committed to version control
6. **Use transactions** for complex migrations to ensure atomicity
#### Example Migration
```sql
-- Add user preferences table
CREATE TABLE user_preferences
(
user_id UUID PRIMARY KEY REFERENCES users (id),
theme VARCHAR(50) NOT NULL DEFAULT 'light',
notifications BOOLEAN NOT NULL DEFAULT TRUE,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- Add index for common queries
CREATE INDEX idx_user_preferences_theme ON user_preferences (theme);
-- Add comment to table
COMMENT ON TABLE user_preferences IS 'Table storing user preference settings';
```
#### Flyway Configuration
The Flyway configuration is defined in `application-repository.yml`:
```yaml
spring:
flyway:
enabled: true
baseline-on-migrate: true
locations: classpath:db/migration
table: flyway_schema_history
```
## Integration
The Repository Module is used by:
- Service implementations that need to persist or retrieve data
- Application configuration for database setup
- Other modules that need data access capabilities
## Configuration
The module includes repository-specific configuration in `application-repository.yml`, which can be customized for different environments.
## Usage Examples
### Implementing a Repository
```kotlin
@Repository
interface UserRepository : JpaRepository<UserEntity, UUID> {
fun findByUsername(username: String): UserEntity?
fun findByEmail(email: String): UserEntity?
}
// Using the repository in a service implementation
@Service
class UserServiceImpl(private val userRepository: UserRepository) : UserService {
override fun findByUsername(username: String): User? {
return userRepository.findByUsername(username)?.toDomain()
}
}
```
## Development
When extending this module:
1. Use Flyway migrations for database schema changes
2. Follow naming conventions for database objects
3. Add appropriate indexes for frequently queried columns
4. Document table structures and relationships
5. Ensure proper transaction management
build-logic/README.md 0 → 100644
Просмотр файла @ f55854d9
# Build Logic Module
## Overview
The Build Logic module contains Gradle convention plugins that define common build configurations, dependencies, and tasks used across different modules in the Effective Office project. These plugins help maintain consistency in the build process and reduce duplication in build scripts.
## Features
- Centralized dependency management
- Reusable build configurations
- Standardized plugin application
- Common task definitions
- Consistent project setup
## Structure
```
build-logic/
├── build.gradle.kts # Build script for the build-logic module
├── settings.gradle.kts # Settings for the build-logic module
└── src/
└── main/
└── kotlin/
└── band/
└── effective/
└── office/
└── backend/
├── kotlin-common.gradle.kts # Common Kotlin configuration
├── spring-boot-application.gradle.kts # Spring Boot application configuration
├── spring-boot-common.gradle.kts # Common Spring Boot configuration
├── spring-data-jpa.gradle.kts # Spring Data JPA configuration
├── band.effective.office.client.kmp.data.gradle.kts # KMP data module configuration
├── band.effective.office.client.kmp.domain.gradle.kts # KMP domain module configuration
├── band.effective.office.client.kmp.feature.gradle.kts # KMP feature module configuration
├── band.effective.office.client.kmp.library.gradle.kts # KMP library module configuration
├── band.effective.office.client.kmp.ui.gradle.kts # KMP UI module configuration
└── ProjectExtensions.kt # Kotlin extensions for project configuration
```
## Convention Plugins
### Backend Plugins
- **kotlin-common**: Common Kotlin configuration for backend modules
- **spring-boot-application**: Configuration for Spring Boot application modules
- **spring-boot-common**: Common Spring Boot configuration for backend modules
- **spring-data-jpa**: Configuration for modules using Spring Data JPA
### Client Plugins
- **client.kmp.data**: Configuration for KMP data modules
- **client.kmp.domain**: Configuration for KMP domain modules
- **client.kmp.feature**: Configuration for KMP feature modules
- **client.kmp.library**: Configuration for KMP library modules
- **client.kmp.ui**: Configuration for KMP UI modules
## Usage
### Applying Plugins
To use these convention plugins in a module, add the appropriate plugin to the module's build script:
```kotlin
plugins {
id("band.effective.office.backend.kotlin-common")
}
```
### Example: Setting up a Spring Boot Application Module
```kotlin
plugins {
id("band.effective.office.backend.spring-boot-application")
}
dependencies {
implementation(project(":backend:core:domain"))
implementation(project(":backend:feature:user"))
// Additional dependencies
}
```
### Example: Setting up a KMP Feature Module
```kotlin
plugins {
id("band.effective.office.client.kmp.feature")
}
dependencies {
implementation(project(":clients:shared:domain"))
implementation(project(":clients:shared:ui"))
// Additional dependencies
}
```
## Development
### Adding a New Convention Plugin
To add a new convention plugin:
1. Create a new Gradle script in the appropriate directory
2. Define the plugin logic
3. Register the plugin in the build-logic build script
Example:
```kotlin
// src/main/kotlin/band/effective/office/backend/new-plugin.gradle.kts
plugins {
id("kotlin")
// Other plugins
}
// Configure the plugin
```
## Benefits
- **Consistency**: Ensures consistent configuration across modules
- **Maintainability**: Centralizes build logic for easier updates
- **Reusability**: Allows reuse of common configurations
- **Simplicity**: Simplifies module build scripts
\ No newline at end of file
Поддерживает Markdown
0% или .
You are about to add 0 people to the discussion. Proceed with caution.
Сначала завершите редактирование этого сообщения!
Пожалуйста, зарегистрируйтесь или чтобы прокомментировать