diff --git a/.aiignore b/.aiignore new file mode 100644 index 0000000000000000000000000000000000000000..dd75b1f03f38a1b0c53d7d8dfdd842c358207de1 --- /dev/null +++ b/.aiignore @@ -0,0 +1,17 @@ +# An .aiignore file follows the same syntax as a .gitignore file. +# .gitignore documentation: https://git-scm.com/docs/gitignore +# Junie will ask for explicit approval before view or edit the file or file within a directory listed in .aiignore. +# Only files contents is protected, Junie is still allowed to view file names even if they are listed in .aiignore. +# Be aware that the files you included in .aiignore can still be accessed by Junie in two cases: +# - If Brave Mode is turned on. +# - If a command has been added to the Allowlist — Junie will not ask for confirmation, even if it accesses - files and folders listed in .aiignore. +backend/app/src/main/resources/.env +backend/app/src/main/resources/firebase-credentials.json +backend/app/src/main/resources/google-credentials.json +deploy/dev/.env +deploy/prod/.env +deploy/dev/*.jar +deploy/prod/*.jar +keystore +local.properties +clients/tablet/composeApp/google-services.json \ No newline at end of file diff --git a/.junie/guidelines.md b/.junie/guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..19db2a835af3de60a78333daabfc6297b906feee --- /dev/null +++ b/.junie/guidelines.md @@ -0,0 +1,281 @@ +# Project Guidelines for Junie + +## Project Overview +Effective Office is a multi-module Kotlin application aimed at automating office processes and providing statistics for employees. The project follows a client-server architecture with a Spring Boot backend, multiple client applications including an iOS tablet app, and Docker-based containerization for deployment. + +## Project Structure +``` +effective-office/ +├── backend/ # Server-side Spring Boot application with PostgreSQL +├── clients/ # Client applications +├── iosApp/ # iOS tablet application +├── deploy/ # Deployment configurations (dev and prod environments) +├── scripts/ # Utility scripts and git hooks +├── build-logic/ # Build configuration +├── docs/ # Project documentation +└── media/ # Media assets +``` + +## Running Tests +Tests can be run using Gradle: +``` +./gradlew test +``` + +For specific modules: +``` +./gradlew :backend:app:test +./gradlew :clients:android:test +``` + +## Build Guidelines +Before submitting changes, Junie should build the project to ensure it compiles correctly: +``` +./gradlew build +``` + +## Code Style Guidelines +1. Follow Kotlin coding conventions for all development +2. Use consistent naming patterns across the codebase +3. Document public APIs and complex logic +4. Ensure no secrets or sensitive information is included in the code +5. Maintain the multi-module structure of the project + +## Security Guidelines +1. Never commit sensitive information like API keys or credentials +2. Use environment variables for configuration as shown in the .env.example files +3. Be aware of the pre-commit hooks that scan for potential secrets using Gitleaks + +## Feature Development Guidelines +### Modular Architecture +1. Every feature should be implemented as a separate feature module +2. Feature modules should be independent and self-contained +3. Feature modules should only depend on core modules, not on other feature modules +4. New features should be added by creating a new module in the appropriate directory: + ``` + effective-office/ + ├── backend/ + │ ├── features/ + │ │ ├── feature-a/ # Feature module A + │ │ ├── feature-b/ # Feature module B + │ │ └── new-feature/ # New feature module + ``` + +### Core Entities +1. Core entities must be placed in appropriate core modules +2. Domain models should be in the `domain` module +3. Data models should be in the `data` module +4. UI components should be in the `ui` module + +### Clean Architecture +The project follows Clean Architecture principles: +1. **Domain Layer**: Contains business logic and entities + - Independent of frameworks and UI + - Contains use cases, entities, and repository interfaces +2. **Data Layer**: Implements repository interfaces from the domain layer + - Contains repository implementations, data sources, and mappers +3. **Presentation Layer**: Contains UI components and view models + - Depends on the domain layer, not on the data layer +4. **Dependencies flow from outer layers to inner layers**: + ``` + UI/Presentation → Domain ← Data + ``` + +### SOLID Principles +1. **Single Responsibility Principle**: Each class should have only one reason to change +2. **Open/Closed Principle**: Software entities should be open for extension but closed for modification +3. **Liskov Substitution Principle**: Objects of a superclass should be replaceable with objects of subclasses without affecting correctness +4. **Interface Segregation Principle**: Many client-specific interfaces are better than one general-purpose interface +5. **Dependency Inversion Principle**: Depend on abstractions, not on concretions + +### DRY and KISS Patterns +1. **DRY (Don't Repeat Yourself)**: + - Avoid code duplication + - Extract common functionality into reusable components + - Use shared modules for code that's used across multiple features +2. **KISS (Keep It Simple, Stupid)**: + - Prefer simple solutions over complex ones + - Write code that is easy to understand and maintain + - Avoid premature optimization + +## Client Application Development Guidelines +### Navigation Framework +1. **Compose Navigation**: + - Use Jetpack Navigation Component for Android applications + - Implement type-safe navigation with sealed classes for destinations + - Use NavHost for managing navigation between composables + +2. **KMP Navigation**: + - Use Decompose for shared navigation logic across platforms + - Implement platform-specific navigation adapters + - Maintain a consistent navigation state model across platforms + +### UI Implementation +1. **Compose Multiplatform**: + - Use Compose Multiplatform for KMP applications for shared UI components across platforms + - Implement a design system with shared tokens (colors, typography, spacing) + - Create platform-specific UI adaptations when necessary + - Use expect/actual declarations for platform-specific UI implementations + +2. **Responsive Design**: + - Implement responsive layouts that adapt to different screen sizes + - Use adaptive layouts for different form factors (phone, tablet, desktop) + - Consider accessibility requirements in UI design + +### Kotlin Multiplatform (KMP) Considerations +1. **Shared Code Organization**: + - Place shared business logic in `commonMain` source set + - Use platform-specific source sets (`androidMain`, `iosMain`) for platform-specific implementations + - Leverage the `expect/actual` pattern for platform-specific APIs + +2. **Dependency Management**: + - Use multiplatform libraries when available + - Implement platform-specific adapters for platform-specific libraries + - Maintain consistent versioning across platforms + +3. **Testing Strategy**: + - Write platform-independent tests in `commonTest` + - Implement platform-specific tests in platform-specific test source sets + - Use mocks and test doubles for external dependencies + +### Native Android Application Tech Stack +1. **Architecture Components**: + - Use ViewModel for UI state management + - Implement Jetpack Compose for declarative UI + - Use Hilt for dependency injection + - Implement Room for local data persistence + +2. **Networking**: + - Use Coroutines and Flow for asynchronous operations + +3. **UI Components**: + - Follow Material 3 design guidelines + - Use Compose Material 3 components + - Implement custom theming consistent with the design system + +### General Tech Stack Considerations +1. **Performance**: + - Optimize startup time and UI rendering + - Use background processing for heavy operations + +2. **Security**: + - Implement secure storage for sensitive data + - Use HTTPS for all network communications + - Follow platform-specific security best practices + +3. **Maintainability**: + - Document architecture decisions and component interactions + - Implement comprehensive logging for debugging + +## Gradle Convention Plugins Guidelines + +### Overview +The `build-logic` module contains Gradle convention plugins that define common build configurations, dependencies, and tasks used across different modules in the project. These plugins help maintain consistency in the build process and reduce duplication in build scripts. + +### 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 + +### 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 +``` + +### Available 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 + +### Using Convention Plugins + +#### 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 +} +``` + +### Creating New Convention Plugins +To add a new convention plugin: + +1. Create a new Gradle script in the appropriate directory under `src/main/kotlin/band/effective/office/` +2. Define the plugin logic using Kotlin DSL +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 +``` + +### Best Practices +1. **Keep plugins focused**: Each plugin should have a single responsibility +2. **Document plugin behavior**: Add comments explaining what the plugin does +3. **Reuse existing plugins**: Compose new plugins from existing ones when possible +4. **Follow naming conventions**: Use consistent naming for plugins +5. **Test changes**: Verify that changes to plugins don't break existing modules +6. **Version control**: Update all affected modules when changing plugin behavior diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md new file mode 100644 index 0000000000000000000000000000000000000000..00404fe8e0d941c2e5ae1d0d6cc386001e400cc8 --- /dev/null +++ b/CONTRIBUTION.md @@ -0,0 +1,166 @@ +# Contributing to Effective Office + +Thank you for your interest in contributing to Effective Office! This document provides guidelines for contributing to the project. + +## Table of Contents +- [Code of Conduct](#code-of-conduct) +- [Development Workflow](#development-workflow) +- [Coding Standards](#coding-standards) +- [Pull Request Process](#pull-request-process) +- [Testing Guidelines](#testing-guidelines) +- [Documentation](#documentation) +- [Feature Development Guidelines](#feature-development-guidelines) +- [Security Guidelines](#security-guidelines) +- [Build Guidelines](#build-guidelines) + +## Code of Conduct + +We expect all contributors to follow these basic principles: +- Be respectful and inclusive +- Provide constructive feedback +- Focus on what is best for the community +- Show empathy towards other community members + +## Development Workflow + +We follow a modified Git Flow branching model. For detailed information, please refer to our [Git Flow](docs/GIT_FLOW.md). + +### Branching Strategy +- **main**: Production-ready code +- **develop**: Integration branch for features +- **feature/**: For developing new features +- **bugfix/**: For fixing non-critical bugs +- **hotfix/**: For critical fixes +- **release/**: For preparing releases + +### Feature Development Process +1. Create a feature branch from `develop`: + ```bash + git checkout develop + git pull + git checkout -b feature/your-feature-name + ``` + +2. Work on your feature, committing changes regularly +3. Push your branch to the remote repository +4. Create a Pull Request to merge into `develop` + +## Coding Standards + +### General Guidelines +1. Follow Kotlin coding conventions for all development +2. Use consistent naming patterns across the codebase +3. Document public APIs and complex logic +4. Ensure no secrets or sensitive information is included in the code +5. Maintain the multi-module structure of the project + +### Commit Message Guidelines +We follow these conventions for commit messages: +- Start with a type: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` +- Use the imperative mood ("Add feature" not "Added feature") +- Keep the first line under 50 characters +- Provide more detailed explanations in subsequent lines if necessary + +Example: +``` +feat: Add user authentication system + +- Implement JWT token generation +- Add login and registration endpoints +- Create user repository and service +``` + +## Pull Request Process + +1. Update documentation with details of changes if appropriate +2. Update version numbers in any examples files and documentation +3. Ensure all CI checks pass before requesting a review +4. You may merge the Pull Request once you have the sign-off of at least one other developer + +## Testing Guidelines + +Tests can be run using Gradle: +```bash +./gradlew test +``` + +For specific modules: +```bash +./gradlew :backend:app:test +./gradlew :clients:android:test +``` + +### Testing Requirements +- Write unit tests for all new features +- Ensure existing tests pass before submitting a PR +- Include integration tests for API endpoints +- For KMP modules, write platform-independent tests in `commonTest` + +For more detailed testing guidelines, see our [Wiki: Testing Guidelines](https://github.com/effective-dev-opensource/Effective-Office/wiki/Testing-Guidelines). + +## Documentation + +- Update README files when adding new features or making significant changes +- Document public APIs with KDoc comments +- Keep documentation up-to-date with code changes +- Add comments for complex logic + +## Feature Development Guidelines + +For comprehensive feature development guidelines, please refer to our [Wiki: Feature Development Guidelines](https://github.com/effective-dev-opensource/Effective-Office/wiki/Feature-Development-Guidelines). + +### Modular Architecture +1. Every feature should be implemented as a separate feature module +2. Feature modules should be independent and self-contained +3. Feature modules should only depend on core modules, not on other feature modules +4. New features should be added by creating a new module in the appropriate directory + +### Clean Architecture +The project follows Clean Architecture principles: +1. **Domain Layer**: Contains business logic and entities +2. **Data Layer**: Implements repository interfaces from the domain layer +3. **Presentation Layer**: Contains UI components and view models +4. **Dependencies flow from outer layers to inner layers** + +### SOLID Principles +1. **Single Responsibility Principle**: Each class should have only one reason to change +2. **Open/Closed Principle**: Software entities should be open for extension but closed for modification +3. **Liskov Substitution Principle**: Objects of a superclass should be replaceable with objects of subclasses without affecting correctness +4. **Interface Segregation Principle**: Many client-specific interfaces are better than one general-purpose interface +5. **Dependency Inversion Principle**: Depend on abstractions, not on concretions + +## Security Guidelines + +1. Never commit sensitive information like API keys or credentials +2. Use environment variables for configuration as shown in the .env.example files +3. Be aware of the pre-commit hooks that scan for potential secrets using Gitleaks +4. Follow secure coding practices to prevent common vulnerabilities + +For more information, see our [Wiki: Security Guidelines](https://github.com/effective-dev-opensource/Effective-Office/wiki/Security-Guidelines). + +## Build Guidelines + +Before submitting changes, build the project to ensure it compiles correctly: +```bash +./gradlew build +``` + +For specific components, use the appropriate Gradle tasks. + +For detailed build instructions, see our [Wiki: Build Guidelines](https://github.com/effective-dev-opensource/Effective-Office/wiki/Build-Guidelines). + +## Additional Resources + +For more detailed information on any aspect of contributing to Effective Office, please refer to our comprehensive [Wiki documentation](https://github.com/effective-dev-opensource/Effective-Office/wiki). + +## Questions or Need Help? + +If you have questions or need help with the contribution process, please reach out to the project maintainers: +- [Alex Korovyansky](https://t.me/alexkorovyansky) +- [Matvey Avgul](https://t.me/matthewavgul) +- [Tatyana Terleeva](https://t.me/tatyana_terleeva) +- [Stanislav Radchenko](https://github.com/Radch-enko) +- [Vitaly Smirnov](https://github.com/KrugarValdes) +- [Victoria Maksimovna](https://t.me/the_koheskine) + +Thank you for contributing to Effective Office! diff --git a/README.md b/README.md index 97b43f5944db7c89f88b2f810db6bf8fb954dfe1..4892515da03fde71bc5771673b369c99b69a32ee 100644 --- a/README.md +++ b/README.md @@ -28,16 +28,7 @@ technologies as little as possible. | Early Room Release | Free up the room before the end of the reservation | | Google Calendar Integration| Syncs all bookings with Google Calendar | -## Architecture - -The project follows a client-server architecture: - -- **Backend**: Spring Boot application with PostgreSQL database -- **Clients**: Client applications and iOS tablet app -- **Deployment**: Docker-based containerization for easy deployment -- **Security**: Git hooks for leak detection to prevent sensitive information exposure - -## Getting Started +## Quick Start ### Prerequisites @@ -49,37 +40,49 @@ The project follows a client-server architecture: ### Installation 1. Clone the repository: - ``` - git clone https://github.com/effective-dev-opensource/Effective-Office - cd effective-office + ```bash + git clone https://github.com/effective-dev-opensource/Effective-Office.git + cd Effective-Office ``` -2. Run the installation script to set up git hooks: - ``` +2. Install Git hooks for development: + ```bash ./scripts/install.sh ``` - This script installs a pre-commit hook that scans for potential secrets using Gitleaks. -3. Set up environment variables: - ``` - cp deploy/dev/.env.example deploy/dev/.env +3. Configure environment variables: + ```bash + cp backend/app/src/main/resources/env.example backend/app/src/main/resources/.env ``` - Edit the `.env` file with your configuration. -4. Build and run the application: - ``` +4. Set up required credentials: + - Add `google-credentials.json` for Google Calendar API + - Add `firebase-credentials.json` for Firebase notifications + - Generate keystore files for Android applications + +5. Run the backend (using Docker): + ```bash cd deploy/dev docker-compose up -d ``` + Or run locally without Docker: + ```bash + # Start PostgreSQL + docker run --name postgres-effectiveoffice -e POSTGRES_DB=effectiveoffice -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:15-alpine + + # Run the backend + ./gradlew :backend:app:bootRun --args='--spring.profiles.active=local' + ``` + +For detailed installation instructions, including setting up credentials and running client applications, see our [Getting Started Guide](https://github.com/effective-dev-opensource/Effective-Office/wiki/Getting-Started-with-Effective-Office) in the wiki. + ## Project Structure ``` effective-office/ -├── backend/ # Server-side application -│ └── README.md # Detailed backend documentation +├── backend/ # Server-side Spring Boot application with PostgreSQL ├── clients/ # Client applications -│ └── README.md # Detailed client documentation ├── iosApp/ # iOS tablet application ├── deploy/ # Deployment configurations │ ├── dev/ # Development environment @@ -90,33 +93,13 @@ effective-office/ └── build-logic/ # Build configuration ``` -For detailed documentation: - -- [Backend Documentation](./backend/README.md) -- [Client Documentation](./clients/README.md) -- [Build Logic Documentation](./build-logic/README.md) -- [Calendar Integration Documentation](docs/CALENDAR_INTEGRATION.md) - -## Development Tools - -- **Build System**: Gradle with Kotlin DSL -- **Containerization**: Docker and Docker Compose -- **Security Scanning**: Gitleaks for secret detection -- **Version Control**: Git with pre-commit hooks - -## Code Style & Conventions +## Documentation -- Follow Kotlin coding conventions for backend development -- Use consistent naming patterns across the codebase -- Document public APIs and complex logic -- Run the pre-commit hook to ensure no secrets are committed +For comprehensive documentation, please visit our [Wiki](https://github.com/effective-dev-opensource/Effective-Office/wiki). -## Contributing +## Contributing -Our project is open-source, so we welcome quality contributions! To make your contribution to the -project efficient and easy to check out, you can familiarize yourself with the project's [git flow -and commit rules](docs/GIT_FLOW.md). If you want to solve an existing issue in the project, you can read the list in -the issues tab in the repository. +We welcome contributions! Please see our [CONTRIBUTION.md](CONTRIBUTION.md) file for guidelines. ## Roadmap **TV App** @@ -135,6 +118,13 @@ An application for tracking foosball match results. It allows users to log games ## Authors +- [Alex Korovyansky](https://t.me/alexkorovyansky) +- [Matvey Avgul](https://t.me/matthewavgul) +- [Tatyana Terleeva](https://t.me/tatyana_terleeva) - [Stanislav Radchenko](https://github.com/Radch-enko) - [Vitaly Smirnov](https://github.com/KrugarValdes) +- [Victoria Maksimovna](https://t.me/the_koheskine) +## License +___ +The code is available as open source under the terms of the [MIT LICENSE](LICENSE). diff --git a/backend/app/src/main/resources/env.example b/backend/app/src/main/resources/env.example new file mode 100644 index 0000000000000000000000000000000000000000..7a607d6ae1b68dc4af07400d1627210de97cff52 --- /dev/null +++ b/backend/app/src/main/resources/env.example @@ -0,0 +1,15 @@ +SPRING_DATASOURCE_URL=jdbc:postgresql://0.0.0.0:5432/effectiveoffice +SPRING_DATASOURCE_USERNAME=postgres +SPRING_DATASOURCE_PASSWORD=postgres + +MIGRATIONS_ENABLE=true +APPLICATION_URL=http://localhost:8080 +LOG_LEVEL=debug + +CALENDAR_APPLICATION_NAME=YourApplicationName +CALENDAR_DELEGATED_USER=yourdelegateduseremail +GOOGLE_CREDENTIALS_FILE=classpath:google-credentials.json + +DEFAULT_APP_EMAIL=yourdefaultappemail +FIREBASE_CREDENTIALS=classpath:firebase-credentials.json +DEFAULT_CALENDAR=yourdefaultcalendar