
(Z)eroMQ — (M)anages — (A) — (G)raphQL
ZMAG is a tool designed for building network APIs rather than traditional web applications, leveraging the unique combination of GraphQL and ZeroMQ. By integrating GraphQL's flexible and efficient querying capabilities with ZeroMQ's high-performance messaging patterns, ZMAG enables developers to create robust and scalable network APIs. This approach allows for real-time communication, seamless data transfer, and efficient management of complex, distributed systems, making ZMAG an ideal choice for developers looking to build sophisticated network services that go beyond the capabilities of standard web applications.
ZMAG is designed to provide a more Pythonic syntax, moving away from the typical GraphQL and ZeroMQ styles and focusing instead on native Python conventions for greater readability and intuitiveness.
Capabilities of ZMAG
- Build GraphQL Queries and Mutations for flexible data interactions.
- Develop Request and Response APIs for efficient communication.
- Implement Pub/Sub and Push/Pull patterns for robust messaging and data distribution.
- Leverage Commands to automate processes and streamline operations.
Built With
Module | Purpose |
---|---|
pyzmq | Core Universal Messaging Library for the API. |
orjson | Fast Python JSON library. |
strawberry | GraphQL Library |
click | Manage the server, development processes, and custom Commands. |
spoc | Framework tool for building this framework. |
Debug Server Built With
Module | Purpose |
---|---|
starlette | Runs the server in Debug mode. |
uvicorn | ASGI web server. |
watchdog | Restarts the debug server on changes. |
Installation
To install ZMAG in different environments, use the following commands:
Development Environment
Server Environment
Client Environment
Warning
ZMAG is currently in its early stages of development, so there may be some changes in the future. However, we aim to keep the public API stable.
Project Flowchart
(API) Application Programming Interface | (CLI) Command-Line Interface |
---|---|
1. Load all Settings . |
1. Load all Settings . |
2. Load Environment Variables . |
2. Load Environment Variables . |
3. Load all Apps (Packages). |
3. Load all Apps (Packages). |
4. Start the ZeroMQ API |
4. Start the CLI Manager. |
flowchart LR;
subgraph ZMAG & Installed Apps
A --> B;
B <--> D;
B <--> E;
end
D <--> F;
E <--> G;
subgraph Your Code
F <--> | GraphQL | H
G <--> | GraphQL | H
end
A{Click};
B[Settings & Apps];
D{The API};
E{The CLI};
F((Operations))
G((Commands))
H{Project};
Explanation
The flowchart illustrates how the project initializes and operates both the API and CLI interfaces:
- Initialization: The process begins with Click, which is used to launch both the API (services) and CLI (commands).
-
Configuration Loading: For both the API and CLI interfaces, all
Settings
,Environment Variables
, andApps (Modules)
are loaded. This ensures the environment is properly configured and all necessary modules are available. -
Starting Interfaces:
Interfaces
- API — the ZeroMQ Backend is started to manage backend processes and facilitate operations.
- CLI — the CLI Manager is initiated using Click, which handles command-line inputs and operations.
-
Integration with GraphQL: Both the API and CLI interfaces can connect to the GraphQL, allowing you to perform GraphQL operations through either the API or the CLI.
-
Custom Extensions: You have the flexibility to create custom CLI commands or API methods, which can leverage the underlying GraphQL capabilities.
Tip
The setup provides a versatile and unified framework, enabling you to manage backend processes and handle command-line operations effectively, with seamless integration of GraphQL functionalities across both interfaces.
Architectural Patterns
These patterns illustrate the flow of communication in a zmag system:
Backend — Frontend
A direct communication pattern where the Backend communicates with the Frontend.
flowchart LR;
A[Backend] <--> B[Frontend];
Backend — Device — Frontend
An intermediary device manages the communication between the Backend and Frontend, allowing for scalability.
flowchart LR;
A[Backend] <--> B((Device)) <--> C[Frontend];
F[Backend] <--> B <--> D[Frontend];
Core Layout
root/ --> <Directory> - Project's Root
|
|-- apps/ --> <Directory> - Project's Apps
|
|-- config/ --> <Directory> - Configurations
| |-- .env --> <Directory> - Environment Settings
| |-- ...
| |-- settings.py --> <File> - Pythonic API Settings
| `-- spoc.toml --> <File> - TOML API Settings
|
`-- etc...
Key Commands
ZMAG comes with several key commands:
Command | Purpose |
---|---|
zmag-init |
Create a new ZMAG project. |
./main.py runserver |
Run the Server. |
./main.py start-app |
Create a ZMAG App inside your apps directory. |
./main.py --help |
Display more information about available commands. |
Important: zmag-init
Command
Use the zmag-init
command only once and make sure you are in a new folder. This command will write files and folders to the current directory.