Development Guide

Development Guide

This guide provides essential information for developers working on the Effective Office system. It covers project setup, architectural patterns, development workflows, and contribution guidelines. This document focuses on the practical aspects of development rather than detailed system architecture.

For a comprehensive guide on setting up and running the project for local development, see Getting Started with Effective Office. For detailed information about module organization and dependency management, see Project Structure. For comprehensive build system configuration and tooling setup, see [Build System & Tooling](Build System & Tooling). For system architecture details, see [System Architecture](System Architecture).

Project Overview

The Effective Office system is a multiplatform office management application consisting of:

• Backend: Spring Boot application with modular architecture
• Tablet Client: Compose Multiplatform application for tablet devices
• Shared Infrastructure: Common build logic and configuration

Module Architecture

The project follows a modular architecture with clear separation between backend and client systems:

Technology Stack

The project uses modern technologies across both backend and client platforms:

Development Environment Setup

Prerequisites

Tool	Version	Purpose
JDK	17+	Backend compilation
Kotlin	2.1.21	Programming language
Android Studio	Latest	Client development
PostgreSQL	12+	Database (for backend)

Key Configuration Files

File	Purpose
settings.gradle.kts	Project module structure
gradle/libs.versions.toml	Dependency version catalog
build-logic/	Shared build configuration

Module Dependencies

The project uses centralized dependency management through the version catalog:

Feature Module Architecture

Each feature module follows a consistent architectural pattern:

Backend Feature Structure

Backend features implement a layered architecture with clear separation of concerns:

Client Feature Structure

Client features use MVI (Model-View-Intent) architecture with Decompose navigation:

Build System Configuration

Convention Plugins

The project uses convention plugins to standardize build configuration:

Plugin	Purpose	Usage
band.effective.office.client.kmp.feature	Client feature modules	Feature modules
band.effective.office.client.kmp.library	Client libraries	Core modules
band.effective.office.client.kmp.ui	UI components	UI modules

Multiplatform Setup

Client modules support multiple platforms through Kotlin Multiplatform:

Development Workflow

Adding a New Backend Feature

1. Create module structure in backend/feature/
2. Add module to settings.gradle.kts
3. Implement controller, service, and repository layers
4. Add database migrations if needed
5. Register components in main application

Adding a New Client Feature

1. Create module structure in clients/tablet/feature/
2. Add module to settings.gradle.kts
3. Apply convention plugin band.effective.office.client.kmp.feature
4. Implement Component, Screen, Intent, and State classes
5. Register navigation routes in main application

Module Communication Patterns

Features communicate through well-defined interfaces:

Testing Strategy

Backend Testing

• Unit tests for services and repositories
• Integration tests with @SpringBootTest
• Test containers for database testing
• MockK for mocking dependencies

Client Testing

• Unit tests for use cases and components
• UI tests with Compose testing framework
• Mock repositories for isolated testing

Key Testing Libraries

Library	Purpose	Version
JUnit Jupiter	Unit testing	5.12.2
MockK	Mocking	1.14.2
Testcontainers	Integration testing	1.20.2
Spring Boot Test	Spring testing	3.5.0

Common Development Tasks

Running the Application

Backend:

./gradlew :backend:app:bootRun

Client (Android):

./gradlew :clients:tablet:composeApp:installDebug

Database Operations

Migrations are managed through Flyway and located in backend/app/src/main/resources/db/migration/.

API Documentation

The backend provides OpenAPI documentation through SpringDoc at /swagger-ui.html when running.