# ayinke-llc/malak architecture

> Architecture diagram of the GitHub repository ayinke-llc/malak, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ayinke-llc/malak
- Repository: https://github.com/ayinke-llc/malak

## Overview

##### Project Type and Purpose
- Malak is an open source tool built for startups and their investors. It is designed to deliver performance insights, manage metrics from integrations (such as Mercury, Brex, Stripe, etc.), send investor updates via email, and handle additional functions like captable and fundraising pipeline management.
- The README notes that while most of the application is open source (core functionality under AGPLv3), a small part concerning integrations/auto-syncing is commercially licensed.
- The project has separate components for API/backend, background processing (cron jobs), and a web-based front end.

##### Main Architectural Components
a. Frontend:
– Located under the “web/ui” directory. This is a NextJS application using Tailwind CSS.
– It provides the user interface for interacting with Malak.
b. Backend API Server:
– Written in Golang and primarily found in the “cmd” and “server” directories.
– Implements REST endpoints for authentication, dashboard and deck management, email updates, security (JWT token usage), and integration with external systems.
c. Background Jobs / Cron Executors:
– Found in “cmd/cron*.go” and deployment scripts. These handle scheduled tasks such as auto-revocation of API keys, deck analytics, synchronization for integrations, scheduled email sending, etc.
d. Datastore and Database:
– Uses PostgreSQL (with migrations in “internal/datastore/postgres/migrations”) as the main data store.
– Also uses Redis for caching (as can be inferred from the “internal/pkg/cache/rediscache”).
e. External Integrations and Modules:
– “internal/integrations” houses integration modules for systems like Brex, Flutterwave, Paystack, etc.
– Additionally, the project supports billing through Stripe (“internal/pkg/billing/stripe”).
– Other modules found in “internal/pkg” cover functionalities for email (with different providers such as SMTP and Resend), chart rendering, geolocation (with MaxMind), JWT management, queuing (with watermill), and social authentication.
f. Secret Management:
– There is a dedicated “internal/secret” module that covers encryption with AES, as well as integrations with secret managers like Vault, AWS SecretsManager, and Infisical.
g. Development and Deployment:
– Configuration and deployment scripts (Dockerfile, docker-compose.yml, deploy directory, and GitHub workflows) point to infrastructure as code practices.
– Migrations, tests, and other dev scripts indicate robust CI/CD and testing practices.

##### Relationships and Data Flow
– The Frontend (NextJS UI) communicates with the Backend API (Golang) via HTTP/REST endpoints. Clearly illustrate a secure channel (with JWT for auth) between these two layers.
– The API server interacts with:
- PostgreSQL for persistent data operations.
- Redis for caching and potentially queuing tasks.
- External services (like billing through Stripe, integrations with Brex, etc.) via dedicated modules.
– Background jobs/cron processes run independently but interface with the same datastore and perform scheduled operations (e.g., sending scheduled emails, revoking API keys).
– Secret management functions are called by both the API and internal modules to load sensitive configuration data, ensuring data security.
– Communication flows should outline request-response pathways (Frontend –> API) as well as backend flows (API –> DB/Cache/External APIs).

##### Architectural Patterns and Design Principles
– The separation between frontend and backend layers shows a clear full-stack design.
– The backend is modular: commands in “cmd”, core domain logic in “server”, datastore access in “internal/datastore”, and integrations in “internal/integrations” all point to separation of concerns.
– Use of migrations and versioned SQL files illustrates a database migration/version control strategy.
– The application leverages background processing (cron jobs) to decouple long-running or scheduled tasks.
– Emphasis on extensibility: integration modules allow plugging in new external services easily.

##### Elements
- Clear labels for each component (e.g., “NextJS Frontend”, “Golang API Server”, “PostgreSQL Database”, “Redis Cache”, “Cron Job Processor”, “External Integrations”, “Secret Manager”).
- Detail interactions that are core to Malak’s purpose, such as metric syncing from external systems and investor update communications via email.

##### Detailed Steps for the Principal Software Engineer
– Then, layer in backend components:
- Internal modules such as authentication (JWT), contact & dashboard management, and update workflows.
- Datastore layer, clearly showing PostgreSQL for persistent data and Redis for caching/queuing.
– Show secret management as an independent service that the backend queries for sensitive configuration.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Client Layer"
        FE["NextJS Frontend"]:::ui
    end

    subgraph "API Server Layer"
        CMD_API["Golang API (cmd)"]:::api
        SERVER_API["Golang API (server)"]:::api
        CMD_API -->|"InternalRouting"| SERVER_API
    end

    subgraph "Data Layer"
        PG["PostgreSQL Database"]:::data
        RC["Redis Cache"]:::data
    end

    subgraph "Background Processing"
        CRON["Cron Jobs Processor"]:::proc
    end

    subgraph "External Services & Integrations"
        EX_INT["External Integrations"]:::ext
        BILL["Billing (Stripe)"]:::ext
        EMAIL["Email Service"]:::ext
        CHART["Chart Rendering"]:::ext
        GEO["Geolocation"]:::ext
        JWT["JWT Management"]:::ext
        QUEUE["Queueing (Watermill)"]:::ext
        SOCIAL["Social Authentication"]:::ext
    end

    subgraph "Secret Management"
        SECRET["Secret Manager"]:::secret
    end

    %% Relationships
    FE -->|"HTTP/REST"| CMD_API
    SERVER_API -->|"CRUD"| PG
    SERVER_API -->|"Caching"| RC
    SERVER_API -->|"LoadSecrets"| SECRET
    SERVER_API -->|"IntegrationCalls"| EX_INT
    SERVER_API -->|"BillingRequests"| BILL
    SERVER_API -->|"EmailDispatch"| EMAIL
    SERVER_API -->|"ChartData"| CHART
    SERVER_API -->|"GeoIPRequests"| GEO
    SERVER_API -->|"JWTAuth"| JWT
    SERVER_API -->|"QueueTasks"| QUEUE
    SERVER_API -->|"SocialAuth"| SOCIAL

    CRON -->|"ScheduledTasks"| PG
    CRON -->|"SyncIntegrations"| EX_INT
    CRON -->|"QueueTasks"| QUEUE
    CRON -->|"LoadSecrets"| SECRET

    %% Click Events
    click FE "https://github.com/ayinke-llc/malak/tree/main/web/ui"
    click CMD_API "https://github.com/ayinke-llc/malak/tree/main/cmd"
    click SERVER_API "https://github.com/ayinke-llc/malak/tree/main/server"
    click CRON "https://github.com/ayinke-llc/malak/blob/main/cmd/cron.go"
    click CRON "https://github.com/ayinke-llc/malak/blob/main/cmd/cron_apikey_revocation.go"
    click CRON "https://github.com/ayinke-llc/malak/blob/main/cmd/cron_deck_analytics.go"
    click CRON "https://github.com/ayinke-llc/malak/blob/main/cmd/cron_integration_sync.go"
    click CRON "https://github.com/ayinke-llc/malak/blob/main/cmd/cron_scheduled_emails.go"
    click PG "https://github.com/ayinke-llc/malak/tree/main/internal/datastore/postgres"
    click PG "https://github.com/ayinke-llc/malak/tree/main/internal/datastore/postgres/migrations"
    click RC "https://github.com/ayinke-llc/malak/tree/main/internal/pkg/cache/rediscache"
    click EX_INT "https://github.com/ayinke-llc/malak/tree/main/internal/integrations"
    click BILL "https://github.com/ayinke-llc/malak/tree/main/internal/pkg/billing/stripe"
    click EMAIL "https://github.com/ayinke-llc/malak/tree/main/internal/pkg/email"
    click CHART "https://github.com/ayinke-llc/malak/tree/main/internal/pkg/chart"
    click GEO "https://github.com/ayinke-llc/malak/tree/main/internal/pkg/geolocation"
    click JWT "https://github.com/ayinke-llc/malak/tree/main/internal/pkg/jwttoken"
    click QUEUE "https://github.com/ayinke-llc/malak/tree/main/internal/pkg/queue"
    click SOCIAL "https://github.com/ayinke-llc/malak/tree/main/internal/pkg/socialauth"
    click SECRET "https://github.com/ayinke-llc/malak/tree/main/internal/secret"

    %% Styles
    classDef ui fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef data fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef proc fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef ext fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef secret fill:#d1ecf1,stroke:#333,stroke-width:2px;
```
