Project Structure
=================

This document provides a comprehensive overview of the Effective Office codebase organization, including module structure, dependency management, build conventions, and architectural patterns. It serves as a navigation guide for developers to understand how the code is organized and how different components relate to each other.

For information about the overall system architecture and component interactions, see [System Architecture](System Architecture). For details about the build system configuration and tooling, see [Build System & Tooling](Build System And Tooling).

Overall Project Organization
----------------------------

The Effective Office codebase is organized as a multi-module Gradle project with clear separation between backend and client systems. The project follows a feature-based modular architecture where each major functionality is isolated into its own module.

![overall-project-organization.svg](media/project-structure/overall-project-organization.svg)

Backend Module Structure
------------------------

The backend system is organized into three main layers: application, core modules, and feature modules. This structure follows clean architecture principles with clear dependency directions.

![backend-project-strucuture.svg](media/project-structure/backend-project-strucuture.svg)

### Backend Core Modules

| Module | Purpose | Key Responsibilities |
|--------|---------|---------------------|
| `backend:core:domain` | Business Models | Entity definitions, domain logic, business rules |
| `backend:core:data` | Data Transfer | DTOs, API request/response models, serialization |
| `backend:core:repository` | Data Persistence | Database access, JPA repositories, data mapping |

### Backend Feature Modules

| Module | Purpose | Key Responsibilities |
|--------|---------|---------------------|
| `backend:feature:authorization` | Security | JWT handling, authentication, authorization |
| `backend:feature:user` | User Management | User CRUD operations, user profiles |
| `backend:feature:workspace` | Room Management | Workspace definitions, room availability |
| `backend:feature:booking:core` | Booking Logic | Booking CRUD, validation, business rules |
| `backend:feature:booking:calendar:google` | Google Integration | Google Calendar API integration |
| `backend:feature:booking:calendar:dummy` | Test Provider | Mock calendar for testing |
| `backend:feature:calendar-subscription` | Notifications | Calendar change subscriptions |
| `backend:feature:notifications` | Push Messaging | Firebase Cloud Messaging integration |

Client Module Structure
-----------------------

The tablet client follows a layered architecture with shared core modules and independent feature modules. Each feature module implements complete user workflows while depending on shared infrastructure.

![client-module-structure.svg](media/project-structure/client-module-structure.svg)

### Client Core Modules

| Module | Purpose | Key Responsibilities |
|--------|---------|---------------------|
| `clients:tablet:core:ui` | UI Components | Reusable Compose components, design system |
| `clients:tablet:core:domain` | Business Logic | Use cases, domain models, business rules |
| `clients:tablet:core:data` | Data Access | Repository implementations, network/local data coordination |

### Client Feature Modules

| Module | Purpose | Key Responsibilities |
|--------|---------|---------------------|
| `clients:tablet:feature:main` | Home Dashboard | Room status display, navigation hub |
| `clients:tablet:feature:settings` | Configuration | App settings, preferences management |
| `clients:tablet:feature:bookingEditor` | Booking Management | Create, edit, and manage bookings |
| `clients:tablet:feature:fastBooking` | Quick Booking | Rapid room reservation interface |
| `clients:tablet:feature:slot` | Time Visualization | Time slot display and interaction |

Dependency Management
---------------------

The project uses Gradle Version Catalogs for centralized dependency management. All versions and library definitions are consolidated in a single TOML file, promoting consistency across modules.

![dependency-managment.svg](media/project-structure/dependency-managment.svg)

### Key Version Definitions

| Component | Version | Purpose |
|-----------|---------|---------|
| Kotlin | 2.1.21 | Primary language for both backend and client |
| Spring Boot | 3.5.0 | Backend web framework |
| Compose | 1.8.1 | UI framework for tablet client |
| Ktor | 3.1.3 | HTTP client for API communication |
| PostgreSQL | 42.7.6 | Database driver |
| Decompose | 3.3.0 | Navigation and component lifecycle |

Build System Architecture
-------------------------

The project uses a custom build logic system with convention plugins to standardize module configuration and reduce build script duplication.

![build-system-architecture.svg](media/project-structure/build-system-architecture.svg)

### Convention Plugin Features

The `band.effective.office.client.kmp.feature` plugin automatically configures:

*   Kotlin Multiplatform with common, Android, and iOS targets
*   Compose Multiplatform UI dependencies
*   Core module dependencies (`core:ui`, `core:domain`, `core:data`)
*   Navigation and lifecycle management (Decompose, Essenty)
*   Dependency injection (Koin)
*   Serialization support

Dependency Injection Architecture
---------------------------------

The project uses Koin for dependency injection in the client and Spring's built-in DI for the backend. The client side organizes dependencies into feature-specific modules that can be composed together.

![dependency-injection-architecture.svg](media/project-structure/dependency-injection-architecture.svg)

### Use Case Composition Pattern

The domain module demonstrates a sophisticated use case composition pattern where complex use cases depend on simpler ones:

    // Example: DeleteBookingUseCase dependencies
    DeleteBookingUseCase(
        networkBookingRepository = get(),
        localBookingRepository = get(),
        getRoomByNameUseCase = get(),
    )

This pattern promotes reusability and maintains clear separation of concerns throughout the application.