Raccoon/docs/tech_manual/module_structure.md

## Module structure

The project has different kinds of modules and, depending on the group a module belongs to, there are some rules about
which other modules it can depend on.

Here is a description of the dependency flow:

- `:androidApp` which is the KMP equivalent of `:app` module in Android-only projects) include `:shared` and can
  include `:core` modules (e.g. for navigation);
- `:shared` is the heart of the KMP application and it virtually includes every other Gradle module as a dependency (it
  contains in the `DiHelper.kt` files the setup of the DI, so it basically needs to see all Koin modules);
- `:feature` modules are included by :shared and include :domain, :core and :unit modules, but they DO not include other
  each other nor any top level module; some unit modules are used just by one feature (e.g. `:unit:postlist` is used
  only by `:feature:home`) in some other cases multiple features use the same unit (e.g. `:unit:zoomableimage` is used
  by both `:feature:home`, `:feature:search`, `:feature:profile` and `:feature:inbox`);
- `:domain` modules can be used by feature and unit modules and can only include core modules; only exception
  is `:domain:inbox` which is a thin layer on top of `:domain:lemmy` so it depends on it (for inbox related functions);
- `:unit` modules are included by feature modules (and `:shared`) and sometimes by other unit modules in case of highly
  reusable parts of the app; the only notable violation to this rule is `:core:commonui:detailopener-impl` which is a
  special module because it is only included by `:shared` (which does the binding between `:detailopener-api`
  and `:detailopener-impl`) and it includes some unit modules but the fact of a unit module included by a core module in
  general should never happen (instead, the reverse is perfectly ok);
- `:core` modules can sometimes include each other (but without cycles, e.g. `:core:markdown`
  includes `:core:commonui:components` / `:core:utils` because it is a mid-level module and something similar happens
  with `:core:persistecnce` which uses `:core:preferences` / `:core:appearance`)  and nothing else; they are in turn
  used by all the other types of modules.

### Top-level modules

The main module (Android-specific) is `:androidApp`, which contains the Application subclass (`MainApplication`) and the
main activity (`MainActivity`). The latter in its `onCreate(Bundle?)` invokes the `MainView` Composable function which
in turns calls `App`, the main entry point of the multiplatform application which is defined in the `:shared` module.

`:shared` is the top module of the multiplatform application, which includes all the other modules and is not included
by anything (except `:androidApp`). In its `commonMain` source set, this module contains `App`, the application entry
point, the definition on the `MainScreen` (and its ViewModel) hosting the main navigation with the bottom tab bar.
Another important part of this module resides in the platform specific source sets (`androidMain` and `iosMain`
respectively) where two `DiHelper.kt` files (one for each platform) can be found, which contain the setup of the root of
the project's dependency injection in a platform specific way, an initialization function on iOS and a Koin module for
Android (which is included in `MainApplication`).

### Feature modules

These modules correspond to the main functions of the application, i.e. the sections of the main bottom navigation. In
particular:

- `:feature:home` contains the post list tab;
- `:feature:search` contains the Explore tab;
- `:feature:inbox` contains the Inbox tab;
- `:feature:profile` contains the Profile tab;
- `:feature:settings` contains the Settings tab.

### Domain modules

These are purely business logic modules that can be reused to provide application main parts:

- `:domain:identity` contains the repositories and use cases that are related to user identity, authorization and API
  configuration;
- `:domain:lemmy` contains all the Lemmy API interaction logic and is divided into two submodules:
    - `:data` contains all the domain models for Lemmy entities (posts, comments, communities, users, etc);
    - `:pagination` contains the pagination utilities for posts within feeds or comments as well as the navigation logic
      that allows to navigate to previous/next post within a list with automatic pagination;
    - `:repository` contains the repositories that access Lemmy APIs (through the :core:api module) and are used
      to manage the entities contained in the `:data` module;
- `:domain:inbox` contains some uses cases needed to interact with the replies, mentions and private messages
  repositories and coordinate the interaction between inbox-related app components.

### Unit modules

These modules are the building blocks that are used to create user-visible parts of the application, i.e. the various
screens, some of which are reusable in multiple points (e.g. the user detail, community detail or post detail, but also
report/post/comment creation forms, etc.). In some cases even a dialog or a bottom-sheet can become a "unit", especially
if it is used in multiple points or contains a little more than pure UI (e.g. some presentation logic); simple pure-UI
dialogs and sheets are located in the `:core:commonui:modals` module instead (but are being progressively converted to
separate units).

Here is a list of the main unit modules and their purpose:

- `:unit:about` contains the About this app dialog
- `:unit:accountsettings` contains the screen of the remote account settings (web preferences)
- `:unit:ban` contains the modal bottom sheet used to ban a user from a community
- `:unit:chat` contains the chat conversation screen
- `:unit:choosecolor` contains the dialogs and bottom sheets used for theme/color selection
- `:unit:choosefont` contains the bottom sheets used for font selection
- `:unit:communitydetail` contains the community detail screen
- `:unit:communityinfo` contains the community info bottom sheet accessible from community detail
- `:unit:configureswipeactions` contains the screen and bottom sheets to configure swipe actions
- `:unit:configurecontentview` contains the screen used to configure post and comment appearance
- `:unit:createcomment` contains the create comment form
- `:unit:createpost` contains the create post form
- `:unit:drafts` contains the screen uses to display post and comment drafts
- `:unit:drawer` contains the navigation drawer
- `:unit:filteredcontents` contains the screen to access moderated contents, liked/disliked items and bookmarks
- `:unit:instanceinfo` contains the instance info bottom sheet with the list of communities
- `:unit:login` contains the login modal bottom sheet
- `:unit:manageaccounts` contains the modal bottom sheet used to change account
- `:unit:manageban` contains the ban management screen
- `:unit:managesubscriptions` contains the subscription management screen
- `:unit:mentions` contains the mentions section of the Inbox tab
- `:unit:messages` contains the private messages section of the Inbox tab
- `:unit:moderatewithreason` contains the modal bottom sheet for moderation actions that require a reason (remove,
    purge, report, hide)
- `:unit:modlog` contains the moderation log screen
- `:unit:multicommunity` contains the multi-community detail and multi-community editor screens
- `:unit:myaccount` contains the profile logged section of the Profile tab
- `:unit:postdetail` contains the post detail screen
- `:unit:postlist` contains the post list (home) screen
- `:unit:rawcontent` contains the "Raw content" dialog with the custom (Android) text toolbar
- `:unit:replies` contains the replies section of the Inbox tab
- `:unit:reportlist` contains the report list screen (for moderators)
- `:unit:selectcommunity` contains the dialog used to select communities (for cross-posts)
- `:unit:selectinstance` contains the bottom sheet used to change instance in anonymous mode
- `:unit:userdetail` contains the user detail screen
- `:unit:userinfo` contains the user information bottom sheet accessible from user detail
- `:unit:web` contains the internal WebView screen
- `:unit:zoomableimage` contains the image detail screen used to display full-screen images.

### Core modules

These are the foundational blocks containing the design system and various reusable utilities that are called throughout
the whole project. Here is a short description of them:

- `:core:api` contains the Ktorfit services used to interact with Lemmy APIs and all the data transfer objects (DTOs)
  used to send and receive data from the APIs;
- `:core:appearance` contains the look and feel repository which exposes the information about the current theme as
  observable states and allows to change them;
- `:core:architecture` contains the building blocks for the Model-View-Intent architecture used in all the screens of
  the application;
- `:core:commonui` contains a series of submodules that are used to define UI components used in the app and reusable
  UI blocks:
    - `:components`: a collection of components that represent graphical widgets
    - `:detailopener-api` : a utility module used to expose an API to centralize content opening (post detail,
      community, detail, user detail, comment creation and post creation)
    - `:detailopener-impl`: implementation of the detail opener, this is an exception to the module architecture because
      it is a core module which includes unit modules so the important thing is
      that no one **ever** include this module except for `:shared`;
    - `:lemmyui`: graphical components used to represent Lemmy UI (posts, comments, inbox items, etc.) and reusable
      subcomponents such as different types of headers, footers, cards, etc.
    - `:modals`: definition of modal bottom sheets and dialogs that have no presentation logic. This module was
      historically much bigger and over time components were migrated to separate units
      modules;
- `:core:markdown` contains Markdown rendering logic;
- `core:l10n` contains all the localization messages and the `L10nManager` interface which acts as a wrapper around
  Lyricist to load the internationalized messages;
- `:core:navigation` contains the navigation manager used for stack navigation, bottom sheet navigation and a
  coordinator for the events originated by the navigation drawer;
- `:core:notifications` contains the `NotificationCenter` contract and implementation as well as the event definition,
  this is used as an event bus throughout the whole project;
- `:core:persistence` contains the local database (primary storage) management logic as well as SQLDelight definitions
  of entities and migrations, plus all the local data sources that are used
  to access the database;
- `:core:preferences` contains the shared preferences/user defaults (secondary storage) and relies on the
  multiplatform-settings library to offer a temporary key-value store;
- `:core:resources` is a wrapper around the resource loading (fonts and images mainly) which used to rely on an external
  library and now used the built-in resource management of Compose;
- `:core:utils`: contains a series of helper and utility functions/classes that are used in the project but were not big
  enough to be converted to separate domain/core modules on their own.

On second thoughts:

- `:core:commonui` has still too much in it, especially `:modals` packages should become unit modules;
- `:core:persistence` belongs more to domain modules, e.g. `:domain:accounts`/`:domain:settings` but it is implemented
  as a core module because is is strongly tied to SQLDelight and its generated code which provides the named queries to
  fetch/save data to the local DB.