I recently launched the beta version of Monavo, a Telegram-first service for token swaps on the Solana network. The project is currently running in public testing, and the main goal of this stage is to observe how the architecture behaves in a real production environment. In this article, I want to explain the Monavo architecture, why the system is split between an edge API and a private backend service, and what engineering decisions help protect the system from duplicate requests, network issues, and unreliable external APIs.
When working with cryptocurrency transactions, infrastructure becomes just as important as the user interface. A duplicated request or network retry can potentially trigger the same operation twice. Because of that, the main focus during the development of Monavo was reliability. The system needed to remain predictable even when dealing with unstable networks, webhook retries, and third-party API limits.
Monavo was designed as a Telegram-first product. Telegram is responsible for authentication, notifications, and action triggers. The web application (/app) is used to confirm operations and display transaction details before they are executed.
🧩 Overall System Architecture
Monavo is implemented as a monorepo with clearly separated modules. This structure keeps business logic isolated from infrastructure and makes the project easier to evolve over time.
The system has several core components. A public API runs on Cloudflare Workers and receives all incoming requests. A separate backend service performs heavier operations and interacts with the Solana ecosystem. The web application acts as the user interface where transactions are reviewed and confirmed.
Shared data contracts and types live in a dedicated package, while the database schema and migrations are maintained in a separate module. This structure allows infrastructure or UI layers to evolve independently without affecting the domain logic.
⚡ Edge Architecture
One of the most important architectural decisions in Monavo was to adopt an edge-first design.
The public API runs entirely on Cloudflare Workers. Workers process Telegram webhooks, handle requests from the web app, manage user sessions, and apply rate limiting.
Workers effectively act as a gateway between users and the internal backend service. This approach ensures that the public interface remains fast while critical logic stays isolated from direct internet access.
Since Workers run on Cloudflare’s edge network across multiple regions, API responses remain fast regardless of where users are located.
🔐 Private Swap Engine
The heavy business logic is handled by a separate internal service, often referred to as the swap engine. This service prepares swap transactions and interacts with Solana infrastructure.
The backend server is not publicly accessible. It runs behind a Cloudflare Tunnel and accepts requests only from Workers.
This separation means the internal service is never exposed directly to the internet. Even if the public API is targeted by attacks, the core swap engine remains unreachable from outside the system.
Workers communicate with the backend using a service authorization key that is validated by the server. This creates a clear security boundary between the edge layer and the internal infrastructure.
🧠 API Contracts and DTOs
All data exchange within the system is built around DTO contracts. Every incoming and outgoing payload is validated at the API boundary.
These contracts are defined using Zod and serve as a shared source of types across all parts of the system. This ensures that every service interprets the same data structures consistently.
This approach significantly reduces the risk of runtime errors and makes the API easier to maintain as the project evolves.
🧯 Result-Based Error Handling Instead of Exceptions
Monavo follows an approach similar to functional languages such as Elixir or Rust. Instead of throwing exceptions, functions return structured result objects.
Each response includes an isFault flag that indicates whether an error occurred. If an error happens, the response also includes an error code and a message.
This approach prevents unexpected exceptions from interrupting execution flows. Clients always receive a predictable response structure and can safely handle errors.
Example responses look like this:
{
"isFault": false,
"data": {}
}
or
{
"isFault": true,
"code": "RATE_LIMIT",
"message": "Too many requests"
}
🔁 Protection Against Duplicate Requests
One of the most common issues in distributed systems is duplicate requests. These may appear due to network retries, repeated HTTP requests, or duplicated webhook deliveries.
To address this, Monavo implements idempotency for command operations. Each request receives a unique key, and the system stores both the request hash and its result.
If the same request is received again, the previously stored response is returned. If the payload differs, the server returns a conflict error.
This mechanism ensures that operations cannot be accidentally executed multiple times.
🛡 Session Security
User authentication begins in Telegram. After authentication, the web application receives a one-time token used to establish a session.
This token has a limited lifetime and is stored in the database only as a hash. Once consumed, it becomes invalid.
The session itself is stored in a secure cookie with the following security attributes:
- HttpOnly
- SameSite
- Secure (in production)
Session tokens are also periodically rotated, which reduces the risk of token compromise.
⚙️ Reliability of External Integrations
Monavo interacts with several external services, including Solana infrastructure providers.
To prevent API overload and accidental blocking, these integrations are wrapped in request rate limiters. Additional caching and periodic updates are used to reduce external load and improve system responsiveness.
This combination ensures that the system remains stable even when external services behave unpredictably.
📦 Deployment
Workers are deployed using GitHub Actions. Whenever code changes are pushed, the deployment pipeline automatically updates the Cloudflare Workers environment.
Deployment uses configuration options that prevent accidental overwriting of runtime secrets and environment variables.
The internal backend service runs on a VPS and is managed with PM2. This setup allows fast updates and provides a simple mechanism for monitoring and restarting the service if necessary.
⚠️ Problems and Lessons Learned
Despite the planned architecture, several issues appeared during early testing of Monavo.
The first problem involved Telegram webhooks. Initially the system did not use idempotency. In practice, Telegram sometimes delivers the same event multiple times, especially during network delays or webhook retries.
This occasionally caused the same operation to run twice. The solution was to introduce idempotency keys and payload hashing so duplicate requests return the original result.
Another issue appeared after moving the entire API to Cloudflare Workers. Workers are excellent for fast API operations, but they are not ideal for long-running or computationally heavy tasks.
Some swap flows required longer execution times than edge functions comfortably support. As a result, the architecture was adjusted so Workers act as a gateway while heavy operations run on a dedicated backend service.
A third challenge appeared when interacting with Solana RPC nodes. Everything seemed stable during testing, but higher request volumes led to rate limit errors and inconsistent responses.
This required adding request limiters, caching layers, and controlled request queues for RPC calls.
Another important lesson came from error handling. Early versions of the system relied heavily on exceptions. Over time this created complex try/catch chains and unpredictable API responses.
Eventually the system was refactored to the result-based approach described earlier. This change made error handling much more predictable and simplified client-side logic.
🧭 Why Monavo Uses This Architecture
The core idea behind the Monavo architecture is to separate the system into two layers.
The edge layer handles user interaction and must remain extremely fast. The core layer executes critical business logic and stays isolated from direct public access.
This approach reduces the attack surface, simplifies scaling, and makes the system more resilient to network instability.
🧪 What Comes Next
Monavo is currently running in beta. The primary goal of this stage is to observe how the architecture performs under real-world conditions and identify potential bottlenecks as the user base grows.
If the system proves stable under production traffic, the next step will be expanding the platform with additional tools for interacting with the Solana ecosystem.
The beta version is already live and gradually opening to more users, so the coming months will provide a good test of how well the current architecture performs in practice.
Top comments (0)