Service Dependencies

Relevant source files

The following files were used as context for generating this wiki page:

• deployment_guide.md
• README.md
• blueprint.md
• TESTING_PLAN.md
• services/api/package.json
• services/api/src/config.ts
• services/api/src/routes/billing.ts

The TempMail Pro email platform is a containerized, multi-service application. Its architecture relies on a set of interconnected services to provide core functionality, data persistence, email handling, and monitoring. Understanding these dependencies is crucial for development, deployment, and maintenance. The system is designed to be self-hosted using Docker and Docker Compose, with clear separation between the frontend, backend, database, and other backing services.

The architecture is built around a Node.js backend, a React frontend, a PostgreSQL database for primary data storage, and Redis for caching and queueing. For production environments, Caddy is used as a reverse proxy to manage traffic and automate HTTPS.

Sources: README.md:19-26, blueprint.md:104-115, deployment_guide.md:4-10

Core Architecture

The platform is composed of several key services that work together. The deployment_guide.md and README.md outline a stack that includes a backend API, a web frontend, a database, a cache, a reverse proxy, and monitoring tools.

Sources: README.md:19-26, deployment_guide.md:65-72

Service Interaction Diagram

This diagram illustrates the high-level interaction between the primary services in a production deployment.

This diagram shows how Caddy acts as the entry point, routing user traffic to the Web UI and API. The API service handles business logic, database interactions, and email processing.

Sources: deployment_guide.md:79-88, blueprint.md:104-115, README.md:19-26

Service Summary

Service	Technology	Purpose	Source Files
API	Node.js, Fastify, Prisma	Backend logic, RESTful API, SMTP server for inbound mail.	services/api/package.json
Web	React, Vite, TailwindCSS	Frontend user interface and dashboard.	services/web/package.json
Database	PostgreSQL	Primary data store for users, domains, inboxes, messages, etc.	deployment_guide.md:66
Cache/Queue	Redis	Caching, session management, and background job processing with BullMQ.	deployment_guide.md:67, services/api/package.json:26
Reverse Proxy	Caddy	Handles incoming HTTP/S traffic, provides automatic SSL via Let's Encrypt.	deployment_guide.md:84-88
Monitoring	Prometheus, Grafana	Collects and visualizes application metrics.	deployment_guide.md:71-72
Outbound Relay	Amazon SES, SendGrid	Optional external SMTP service for reliable outbound email delivery.	deployment_guide.md:92-120
Anti-Abuse	ClamAV, Rspamd	Optional services for virus scanning and spam filtering.	deployment_guide.md:183-199

Sources: README.md:19-26, deployment_guide.md, blueprint.md:104-115

Data Persistence

The application relies on two primary data services for persistence and caching.

PostgreSQL

PostgreSQL is the primary relational database. It stores all core application data, including users, domains, inboxes, and email message metadata. The backend API service connects to it using Prisma ORM.

• Role: Primary data storage.
• Data Model: Includes tables for User, Domain, Inbox, Message, Attachment, AuditLog, and more.
• Connection: The API service uses the DATABASE_URL environment variable to connect to the PostgreSQL instance.

Sources: blueprint.md:162-173, services/api/src/config.ts:16, services/api/test/api.integration.test.ts:10-17

Redis

Redis is used for caching and as a message broker for background jobs via the bullmq library.

• Role: Caching and background job queueing.
• Connection: The API connects to Redis using the REDIS_HOST and REDIS_PORT environment variables, which are configured for the test environment. The bullmq dependency in package.json indicates its use for queueing.

Sources: TESTING_PLAN.md:30, services/api/package.json:26

Application Services

The core logic is split between a backend API and a frontend web application.

API Service (api)

The API service is the backend of the platform, built with Node.js and the Fastify framework. It exposes a RESTful API for the frontend and third-party integrations. It also includes a built-in SMTP server to handle inbound email.

Key dependencies listed in package.json include:

• @fastify/jwt: For JWT-based authentication.
• @prisma/client: For database interaction.
• bullmq: For Redis-based queues.
• smtp-server: To create the inbound SMTP server.
• mailparser: To parse raw email content.
• nodemailer: For handling outbound email.
• prom-client: To expose Prometheus metrics.

Sources: services/api/package.json:22-40, README.md:19

Web Service (web)

The web service is the frontend application built with React, Vite, and styled with TailwindCSS. It consumes the API service to provide a user interface for managing domains, inboxes, and messages.

Key dependencies include:

• react, react-dom, react-router-dom: For building the single-page application.
• tailwindcss: For styling.
• recharts: For rendering charts in the admin dashboard.
• zod: For client-side validation.

Sources: services/web/package.json:15-23, README.md:22

External & Infrastructure Dependencies

These services support the core application by handling traffic, email delivery, and monitoring.

Caddy (Reverse Proxy)

In production, Caddy is used as the reverse proxy. Its primary responsibilities are:

• Terminating TLS (HTTPS).
• Automatically obtaining and renewing SSL certificates from Let's Encrypt.
• Routing traffic to the appropriate backend service (web or api) based on the hostname (e.g., app.yourdomain.com, api.yourdomain.com).

The production deployment guide specifies using docker-compose.prod.yml, which configures Caddy based on DOMAIN and ACME_EMAIL environment variables.

Sources: deployment_guide.md:79-88, README.md:23

Outbound Email Relays

While the platform handles inbound email directly, the documentation strongly recommends using a professional third-party service for sending outbound emails to avoid deliverability issues and IP blacklisting.

• Supported Services: Amazon SES and SendGrid are mentioned as recommended options.
• Configuration: Outbound email is enabled by setting OUTBOUND_ENABLED=true and configuring the relevant SMTP credentials (OUTBOUND_SMTP_* variables) in the .env file.

This diagram shows the flow for sending an email from the platform.

Payment Processing (Stripe)

The application includes a billing module designed to integrate with Stripe for managing subscriptions and tier-based feature limits.

• Functionality: The code defines routes for creating checkout sessions, managing subscriptions, and handling Stripe webhooks.
• Configuration: It relies on environment variables like STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET. The feature is disabled if these are not set.
• Tier Limits: The system enforces limits on resources like domains and inboxes based on the user's subscription tier (FREE, STARTER, PROFESSIONAL).

Sources: services/api/src/routes/billing.ts:13-23, 31-32, 210-252

Test Environment

The testing plan specifies the services required to run integration and end-to-end tests.

• Required Services: PostgreSQL and Redis.
• Configuration: The test environment uses different ports (5433 for Postgres, 6380 for Redis) to avoid conflicts with a local development setup. A separate test database is used, configured via the DATABASE_URL.

This diagram shows the test setup.