Frequency Developer Gateway is a suite of microservices designed to simplify interactions with the Frequency blockchain, bridging the gap between Web2 and Web3 development.
- 📖 About the Project
- 🚀 Live OpenAPI Docs
- 🔍 Architecture Map
- 🔍 Gateway Microservices
- 💻 Getting Started
- 🛫 Deployment
- 📝 Logging
- 📊 Metrics
- ⚡ Load and Stress Testing
- 🤝 Contributing
- 🙏 Acknowledgments
- 📝 License
Gateway is a collection of services designed to simplify interactions with the Frequency blockchain. It bridges the gap between Web2 and Web3, allowing developers to interact with Frequency as easily as they would with any traditional Web2 API.
- Applications (7 services): 3 APIs, 3 workers and 1 watcher
- Libraries (14 libraries): Shared functionality and utilities
- Account (account-api + account-worker): User account management and blockchain interactions
- Content Publishing (content-publishing-api + content-publishing-worker): Content creation and publishing to blockchain
- Graph (graph-api + graph-worker): Social graph and relationship management
- Content Watcher (content-watcher): Monitors blockchain for content changes
- Blockchain: Polkadot/Frequency chain interactions
- Queue: BullMQ job processing
- Cache: Redis caching layer
- Storage: File/IPFS storage
- Config: Environment configuration
- Types: Shared TypeScript definitions
- Framework: NestJS with TypeScript
- Blockchain: Polkadot API for Frequency chain
- Storage: IPFS, file system
- Caching: Redis with Ioredis
- Queues: BullMQ for background jobs
- Documentation: OpenAPI/Swagger
- Testing: Jest
- Infrastructure: Docker, Kubernetes ready
- Modular architecture: Use each service independently to fit your specific needs
- Simplified blockchain interactions: Abstract away complex blockchain operations
- Web2-like experience: Familiar REST API patterns for Web2 developers
- Background Processing: Async job queues for blockchain operations
- Monitoring: Prometheus metrics and structured logging
- Developer-Friendly: Comprehensive documentation and testing
For a practical implementation example, check out our **Social App Template ** here, which demonstrates how to integrate these services into a full-fledged application.
Visit our Live API Documentation to start exploring the Gateway services.
flowchart LR
;
subgraph Custom Logic
C[Client] --> S(Server)
end
subgraph Gateway Microservices
AS[Account Service]
GS[Graph Service]
CPS[Content Publishing Service]
CWS[Content Watcher Service]
end
S --> AS
S --> GS
S --> CPS
S --> CWS
subgraph Public
F(Frequency Network)
end
AS --> F
GS --> F
CPS --> F
CWS --> F
Gateway consists of four independent microservices, each designed to handle specific aspects of interaction with the Frequency blockchain. Below is a detailed overview of each service:
| Service | Description | API Documentation | README |
|---|---|---|---|
| Account Service | Manages user accounts and authentication on the Frequency blockchain using Sign In With Frequency. It handles tasks such as account creation and key management. | API Docs | README |
| Graph Service | Manages social connections and relationships between users on the Frequency network. It handles operations like following/unfollowing users and retrieving social graphs. | API Docs | README |
| Content Publishing Service | Facilitates the creation and publication of content on the Frequency blockchain. It manages tasks such as posting messages, attachments, replies, and reactions. | API Docs | README |
| Content Watcher Service | Monitors and retrieves content updates from the Frequency blockchain. It allows applications to efficiently track new content as it's published. | API Docs | README |
- Modularity: Each service can be used independently, allowing developers to integrate only the functionalities they need.
- Scalability: The microservice architecture allows for easy scaling of individual services based on demand.
- Simplified Blockchain Interaction: These services abstract complex blockchain operations, providing a familiar API-based interface for developers.
- Comprehensive Documentation: Each service comes with detailed API documentation and a README file for easy integration and usage.
Gateway offers flexibility in how you can use its services. You can either quickly set up all services or selectively use specific microservices based on your needs. Below, we provide both a Quick Start guide for setting up all services and information on how to get started with individual microservices.
Follow these steps to quickly get all Gateway services up and running:
- Prerequisites: In order to run this project you need:
- Clone the Repository:
git clone git@github.com:ProjectLibertyLabs/gateway.git
cd gateway- Start all Services (local and testnet development only)
./start.shThis script will start all Gateway microservices using Docker. It is not designed to run against mainnet; it's intended for local development or testing against Paseo Testnet. If you run a local Frequency node via start.sh, it will be its own isolated chain, not connected to mainnet or testnet.
- Stop all Services (local and testnet development only)
./stop.shUse this script when you need to stop all running Gateway services.
- Build Gateway Documentation
# First time installation only
cargo install mdbook@0.4.52
cargo install mdbook-mermaid@0.15.0
cd docs
npm install
mdbook build- Build and Serve Gateway Documentation
cd docs
mdbook serveTo begin using these microservices:
- Decide which services your application needs.
- Review the API documentation for each required service. See the Live Docs or README for more details.
- Integrate the service APIs into your application using the documentation as a guide.
For a practical example of how these services can be used together, check out our Social App Template.
To prepare for deployment, you can use the start and stop scripts against a local node and Paseo testnet. For deployment, it is recommended to set up your mainnet Gateway instance in a cloud environment.
Deployment of each Gateway service has various options. See the Live Docs for more details.
Deployment of the Gateway documentation occurs via merge to main branch via GitHub Actions.
Gateway uses Pino for logging. By default, the log output is JSON formatted.
Set LOG_LEVEL to one of error, warn, info, debug, or trace from least to most verbose.
Default is info.
In addition, if PRETTY=true is set in the .env file for a given app, this applies the pino-pretty decorator in the logs, for a colorized, more human-readable format.
For each app - account-api, account-worker, content-publishing-api, content-publishing-worker, content-watcher,
graph-api, and graph-worker - Gateway exposes the default
Prometheus metrics at /metrics.
A local Prometheus server can be installed and pointed at this endpoint for debugging or other purposes.
Gateway includes Grafana k6 load and stress testing capabilities across microservices to ensure reliability, performance, and scalability under various load conditions.
Key Features:
- Health Check Testing: Basic service availability validation
- Load Testing: Multiple scenarios (light, medium, heavy, burst) for performance validation
- Stress Testing: Advanced stress scenarios with multiple phases
- File Upload Testing: Size-specific testing for content publishing
- Test Data Generation: Realistic data generation to avoid blockchain interaction
Quick Start:
# Run health check for any service
cd apps/[service-name]/k6-test
k6 run health-check.k6.js
# Run load testing with specific scenario
cd apps/content-publishing-api/k6-test
SCENARIO=heavy k6 run batch-announcement-load.k6.jsDetailed information, configuration options, and best practices, are included in our * *k6 testing documentation**.
Contributions, issues, and feature requests are welcome!
Thank you to Frequency for assistance and documentation making this possible.
This project is Apache 2.0 licensed.