≪ View Page

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
software:monolith [2025/12/21 06:42] – diamondsoftware:monolith [2025/12/31 13:36] (current) – update services diamond
Line 1: Line 1:
-# The Monolith+# Monolith
  
-This document provides an overview of the dma.space monolith, its responsibilities, +This document provides an overview of the dma.space monolith, its responsibilities, and how to contribute to its development.
-and how to contribute to its development.+
  
 ## What is the Monolith? ## What is the Monolith?
  
-The monolith is the primary backend application for dma.space. +The monolith is the primary backend application for dma.space's portal. It is a single, unified codebase that provides a wide range of services and functionalities for members and staff. The monolith is written in Go and utilizes the `go.uber.org/fx` framework for dependency injection, which helps in organizing the different components of the application.
-It is a single, unified codebase that provides a wide range of services +
-and functionalities for members and staff. The monolith is written in Go and +
-utilizes the `go.uber.org/fx` framework for dependency injection, which helps in +
-organizing the different components of the application.+
  
 ## Architecture ## Architecture
  
-The monolith is designed to be a central hub for all of DMA's services. For more +The monolith is designed to be a central hub for all of dma.space's services. For more detailed information, you can refer to the [source code](https://codeberg.org/dma/monolith) and the `README.md` file in the repository.
-detailed information, you can refer to the +
-[source code](https://codeberg.org/dma/monolith) and the `README.md` file in the +
-repository.+
  
 ### Dependency Injection ### Dependency Injection
  
-The monolith uses [uber/fx](https://github.com/uber-go/fx) for dependency +The monolith uses [uber/fx](https://github.com/uber-go/fx) for dependency injection. This allows each service to be designed in a modular way, where each service grabs only the dependencies it needs. This design promotes loose coupling and allows services to seamlessly interoperate with each other.
-injection. This allows each service to be designed in a modular way, where each +
-service grabs only the dependencies it needs. This design promotes loose +
-coupling and allows services to seamlessly interoperate with each other.+
  
-For example, the `homeassistant` service exists independently of other +For example, the `homeassistant` service exists independently of other API-related services, but the `spaceapi` service can optionally depend on it to fetch sensor information from Home Assistant for its JSON output.
-API-related services, but the `spaceapi` service can optionally depend on it to +
-fetch sensor information from Home Assistant for its JSON output.+
  
 ### Dependencies ### Dependencies
Line 35: Line 22:
  
 - **PostgreSQL**: Used as the primary database for storing all application data. - **PostgreSQL**: Used as the primary database for storing all application data.
-- **Authentik**: Provides identity and authentication services, handling user +- **Authentik**: Provides identity and authentication services, handling user sign-up, login, and access control.
-  sign-up, login, and access control.+
  
 The monolith can also integrate with the following optional services: The monolith can also integrate with the following optional services:
Line 42: Line 28:
 - **Stripe**: For processing membership dues and other payments. - **Stripe**: For processing membership dues and other payments.
 - **Home Assistant**: For integration with smart home devices and automation. - **Home Assistant**: For integration with smart home devices and automation.
 +- **Zulip**: For synchronizing profile information. **It is not in charge of user role synchronization; this is the job of SCIM.**
 +- **SpaceAPI**: For providing a `/spaceapi.json` endpoint that exposes an API about the state of the physical space, with Home Assistant integration as needed.
  
 ### Responsibilities ### Responsibilities
Line 47: Line 35:
 The monolith is in charge of the following services: The monolith is in charge of the following services:
  
-- **Member Portal**: Provides a web interface for members to manage their +- **Member Portal**: Provides a web interface for members to manage their accounts, memberships, and other related activities. 
-  accounts, memberships, and other related activities. +- **Membership Dues & Billing**: Handles membership payments, billing cycles, and payment processing through Stripe. 
-- **Membership Dues & Billing**: Handles membership payments, billing cycles, +- **Member Inviting & Onboarding**: Manages the process of inviting new members and onboarding them into the system. 
-  and payment processing through Stripe. +- **Notification System**: Sends out notifications to members regarding important events, announcements, and account-related information. 
-- **Member Inviting & Onboarding**: Manages the process of inviting new members +- **Authentication**: Integrates with Authentik for user authentication and authorization using OIDC. 
-  and onboarding them into the system. +- **API**: Exposes a set of APIs for various frontend applications and services to interact with. 
-- **Notification System**: Sends out notifications to members regarding +- **Home Assistant Integration**: Connects with Home Assistant to provide smart home functionalities and automation. 
-  important events, announcements, and account-related information. +- **Space API**: Implements the Space API protocol to provide information about the makerspace's status (e.g., open or closed).
-- **Authentication**: Integrates with Authentik for user authentication and +
-  authorization using OIDC. +
-- **API**: Exposes a set of APIs for various frontend applications and services +
-  to interact with. +
-- **Home Assistant Integration**: Connects with Home Assistant to provide smart +
-  home functionalities and automation. +
-- **Space API**: Implements the Space API protocol to provide information about +
-  the makerspace's status (e.g., open or closed).+
  
 ### Jobs ### Jobs
  
-The monolith runs a background job worker that is responsible for executing +The monolith runs a background job worker that is responsible for executing various automated tasks. These jobs are managed using a PostgreSQL-based job queue. Some of the key jobs include:
-various automated tasks. These jobs are managed using a PostgreSQL-based job +
-queue. Some of the key jobs include:+
  
-- **Syncing Member Billings**: Regularly syncs billing information for all +- **Syncing Member Billings**: Regularly syncs billing information for all members to ensure that their membership status is up-to-date. 
-  members to ensure that their membership status is up-to-date. +- **Processing Notifications**: Sends out pending notifications to members through various channels. 
-- **Processing Notifications**: Sends out pending notifications to members +- **Data Synchronization**: Performs data synchronization tasks with external services like Authentik and Home Assistant.
-  through various channels. +
-- **Data Synchronization**: Performs data synchronization tasks with external +
-  services like Authentik and Home Assistant.+
  
 ### HTTP Routes ### HTTP Routes
Line 81: Line 56:
 The following is a list of all the top-level pages available in the monolith. The following is a list of all the top-level pages available in the monolith.
  
-- `/`: Renders the home page. This is currently a placeholder and will +- `/`: Renders the home page. This is currently a placeholder and will eventually be in charge of rendering the entire dma.space frontpage so that no JavaScript is needed for rendering important information, such as calendar, event agenda, etc.
-  eventually be in charge of rendering the entire dma.space frontpage so that no +
-  JavaScript is needed for rendering important information, such as calendar, +
-  event agenda, etc.+
 - `/login`: Begins the authentication process. - `/login`: Begins the authentication process.
 - `/logout`: Logs the user out. - `/logout`: Logs the user out.
-- `/portal`: Renders the portal dashboard, which contains links to all +- `/portal`: Renders the portal dashboard, which contains links to all member-only pages.
-  member-only pages.+
 - `/spaceapi.json`: Returns the SpaceAPI JSON. - `/spaceapi.json`: Returns the SpaceAPI JSON.
  
Line 97: Line 68:
 ### Where to Contribute ### Where to Contribute
  
-The monolith codebase is located in this repository. The main application entry +The monolith codebase is located in this repository. The main application entry point is at `cmd/dma-monolith/main.go`, and the various services are organized under the `services/` directory.
-point is at `cmd/dma-monolith/main.go`, and the various services are organized +
-under the `services/` directory.+
  
 ### How to Contribute ### How to Contribute
  
-1.  **Set up your development environment**: Follow the instructions in the +1.  **Set up your development environment**: Follow the instructions in the `README.md` file to set up your local development environment. This includes installing the necessary tools like Go, Nix, and Docker. 
-    `README.md` file to set up your local development environment. This includes +2.  **Find an issue to work on**: Look for open issues in the issue tracker. If you have an idea for a new feature or a bug fix, you can create a new issue to discuss it with the team.
-    installing the necessary tools like Go, Nix, and Docker. +
-2.  **Find an issue to work on**: Look for open issues in the issue tracker. If +
-    you have an idea for a new feature or a bug fix, you can create a new issue +
-    to discuss it with the team.+
 3.  **Create a new branch**: Create a new branch for your changes. 3.  **Create a new branch**: Create a new branch for your changes.
-4.  **Write your code**: Make your changes to the codebase, following the +4.  **Write your code**: Make your changes to the codebase, following the existing coding style and conventions.
-    existing coding style and conventions.+
 5.  **Test your changes**: Make sure to add or update tests for your changes. 5.  **Test your changes**: Make sure to add or update tests for your changes.
-6.  **Submit a pull request**: Once you are happy with your changes, submit a +6.  **Submit a pull request**: Once you are happy with your changes, submit a pull request for review.
-    pull request for review.+
  
 ## Point of Contact ## Point of Contact
  
-If you have any questions or need help with the monolith, please reach out to +If you have any questions or need help with the monolith, please reach out to **@diamond**.
-**@diamond**.+