Differences

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

--- software:monolith [2025/12/21 05:42] – created diamond
+++ software:monolith [2025/12/31 13:36] (current) – update services diamond
@@ Line 1: / Line 1: @@
-# monolith
+# Monolith
+This document provides an overview of the dma.space monolith, its responsibilities, and how to contribute to its development.
+## What is the Monolith?
+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.
+## Architecture
+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.
+### Dependency Injection
+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.
+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.
+### Dependencies
+To run the monolith, the following external services are required:
+- **PostgreSQL**: Used as the primary database for storing all application data.
+- **Authentik**: Provides identity and authentication services, handling user sign-up, login, and access control.
+The monolith can also integrate with the following optional services:
+- **Stripe**: For processing membership dues and other payments.
+- **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
+The monolith is in charge of the following services:
+- **Member Portal**: Provides a web interface for members to manage their accounts, memberships, and other related activities.
+- **Membership Dues & Billing**: Handles membership payments, billing cycles, and payment processing through Stripe.
+- **Member Inviting & Onboarding**: Manages the process of inviting new members and onboarding them into the system.
+- **Notification System**: Sends out notifications to members regarding important events, announcements, and account-related information.
+- **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
+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:
+- **Syncing Member Billings**: Regularly syncs billing information for all members to ensure that their membership status is up-to-date.
+- **Processing Notifications**: Sends out pending notifications to members through various channels.
+- **Data Synchronization**: Performs data synchronization tasks with external services like Authentik and Home Assistant.
+### HTTP Routes
+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 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.
+- `/logout`: Logs the user out.
+- `/portal`: Renders the portal dashboard, which contains links to all member-only pages.
+- `/spaceapi.json`: Returns the SpaceAPI JSON.
+## Contributing
+We welcome contributions to the monolith! Here’s how you can get started:
+### Where to Contribute
+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.
+### How to Contribute
+.  **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.
+.  **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.
+.  **Create a new branch**: Create a new branch for your changes.
+.  **Write your code**: Make your changes to the codebase, following the existing coding style and conventions.
+.  **Test your changes**: Make sure to add or update tests for your changes.
+.  **Submit a pull request**: Once you are happy with your changes, submit a pull request for review.
+## Point of Contact
+If you have any questions or need help with the monolith, please reach out to **@diamond**.
-The DMA Monolith.