How ayinke-llc/malak works
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!