Welcome to Zeython, a truly modular, fast, and friendly MVC framework for Python that supports multiple services running in parallel. The architecture is designed to be service-agnostic, allowing you to easily add, remove, or configure services without tight coupling.
Zeython is created by Md Mahedi Zaman Zaber and is the improved and advanced version of the earlier project: https://github.com/zaber-dev/MVC-Python
Repository: https://github.com/zaber-dev/Zeython
- Full docs: docs/index.md
- Developer guide: docs/developer-setup.md
- Service-oriented design: Each service (web, Discord, etc.) is completely independent
- Plugin system: Services can be enabled/disabled through configuration
- No tight coupling: Core framework doesn't depend on specific services
- Easy extensibility: Add new services without modifying core code
- Lazy loading: Services are only loaded when enabled
- Threaded execution: Services run in parallel without blocking each other
- Optimized startup: Only configured services are initialized
- Resource management: Proper service lifecycle management
- Clean separation: MVC pattern with clear service boundaries
- Configuration-driven: Enable/disable features through environment variables
- Backward compatible: Existing Discord-specific code continues to work
- Well documented: Clear interfaces and comprehensive examples
.
├── app
│ ├── Actions # Utility functions (pagination, embeds, webhook handling, etc.)
│ ├── Commands # Discord command handling (optional service)
│ │ ├── Context # Traditional Discord commands
│ │ └── Slash # Slash commands for Discord
│ ├── Controllers # Controller logic for web and services
│ │ ├── Flask # Controllers specific to Flask web app
│ │ └── Discord # Controllers for Discord bot (optional)
│ ├── Core # Core framework components
│ │ ├── service.py # Service interface and base classes
│ │ ├── service_manager.py # Service lifecycle management
│ │ └── config.py # Configuration management
│ ├── Models # Data models for the application
│ ├── Services # Service implementations
│ │ ├── web_service.py # Flask web service
│ │ └── discord_service.py # Discord bot service (optional)
│ └── Views # Dynamic Flask views/templates structures
├── config
│ ├── boot.py # Legacy entry point (deprecated)
│ └── application.py # New modular application bootstrap
├── database
│ └── db.py # Database interactions (abstraction layer)
├── resources # Static and template files for Flask
│ ├── css # CSS files
│ ├── js # JavaScript files
│ └── views # HTML templates
├── routes
│ ├── api.py # Routes for API endpoints
│ └── web.py # Routes for web pages
├── storage # User file storage (uploads, etc.)
├── vendor # Placeholder for third-party integrations
├── requirements.txt # Python dependencies
├── Dockerfile # Docker containerization file
└── .env # Environment configuration variables- MVC Structure: Clean separation of concerns with Models, Views, and Controllers
- Flask Integration: Modern Flask web application with blueprint support
- Enhanced Models: Validation, caching, audit trails, and soft deletes
- Service Layer: Repository pattern and business logic separation
- Database Abstraction: Flexible database layer with SQLAlchemy and advanced ORM features
- Template System: Jinja2 templates with organized static files
- API Support: RESTful APIs with comprehensive error handling
- User Management: Enhanced user model with password hashing and account security
- Session Management: Comprehensive session tracking with device information
- JWT Tokens: Access token creation, validation, and revocation
- OAuth Integration: Framework for external OAuth providers (Google, GitHub, Discord)
- Security Audit: Database-backed security event logging with risk assessment
- Password Reset: Secure token-based password reset functionality
- File Upload: Advanced file handling with category-based organization
- Storage Management: Secure file storage with metadata tracking
- Permissions: Granular file access control with user and public permissions
- File Versioning: Track file changes and maintain version history
- Security: Extension validation, size limits, and virus scanning integration
- Plugin Architecture: Extensible framework for third-party service integrations
- API Management: Rate limiting, request tracking, and error handling
- Webhook Support: Comprehensive webhook handling with logging and retry logic
- Vendor Models: Configuration and state management for external services
- Custom Exceptions: Specific exception classes with detailed context
- Error Logging: Database-backed error tracking with occurrence counting
- Activity Logging: Comprehensive user and system activity tracking
- Performance Metrics: Response time tracking and resource usage monitoring
- Context Managers: Automatic error handling and performance monitoring utilities
- Plugin Architecture: Discord service loads only when configured
- Command System: Support for both traditional and slash commands
- Event Handling: Comprehensive Discord event management
- Modular Cogs: Organized command structure
- No Dependencies: Core system works without Discord libraries
- Service Manager: Centralized service lifecycle management
- Configuration System: Environment-based configuration with fallbacks
- Thread Management: Safe parallel execution of services
- Status Monitoring: Real-time service status and health checks
- Hot Swappable: Add/remove services without system restart
- Type Hints: Full type annotation support throughout the codebase
- Comprehensive Testing: Unit tests for all enhanced features
- Documentation: Well-documented APIs with usage examples
- Validation Framework: Field-level validation with custom validators
- Caching System: Model-level caching for improved performance
- JSON Serialization: Full serialization/deserialization support
- Containerization: Complete Docker setup for easy deployment
- Multi-service: Single container can run multiple services
- Environment Configuration: Easy configuration through environment variables
-
Clone the Repository:
git clone https://github.com/zaber-dev/Zeython.git cd Zeython -
Install Dependencies:
pip install -r requirements.txt
-
Configure Services: Copy
.env_exampleto.envand configure your services:cp .env_example .env
For Web Service Only:
FLASK_HOST=127.0.0.1 FLASK_PORT=5000 DATABASE_URL=sqlite:///database.db
For Web + Discord Services:
FLASK_HOST=127.0.0.1 FLASK_PORT=5000 DISCORD_TOKEN=your_discord_token_here DISCORD_PREFIX=! DATABASE_URL=sqlite:///database.db
-
Run the Application:
# New modular system (recommended) python config/application.py # Legacy system (deprecated) python config/boot.py
- Enable: Set
FLASK_HOSTenvironment variable - Port: Set
FLASK_PORT(default: 5000) - Debug: Set
FLASK_DEBUG=truefor development
- Enable: Set
DISCORD_TOKENenvironment variable - Prefix: Set
DISCORD_PREFIX(default: !) - Commands: Add commands in
app/Commands/directories
-
Create Service Class:
from app.Core.service import ThreadedService class MyService(ThreadedService): def is_enabled(self) -> bool: return self.config.get('enabled', False) def _run(self): # Your service logic here pass
-
Register Service:
from app.Core.service_manager import service_manager service_manager.register_service_class(MyService, "my_service")
-
Configure Service:
MY_SERVICE_ENABLED=true MY_SERVICE_OPTION=value
# Build the container
docker build -t zeython .
# Run with web service only
docker run -e FLASK_HOST=0.0.0.0 -e FLASK_PORT=5000 -p 5000:5000 zeython
# Run with multiple services
docker run -e FLASK_HOST=0.0.0.0 -e DISCORD_TOKEN=your_token -p 5000:5000 zeythonAll major TODO items have been implemented! The framework now includes:
- ✅ Vendor Integrations: Complete framework for third-party integrations with rate limiting, webhooks, and plugin architecture
- ✅ Authentication: Comprehensive authentication system with JWT tokens, OAuth integration, and session management
- ✅ File Management: Advanced file handling with categories, permissions, versioning, and storage management
- ✅ Error Handling & Logging: Enhanced error tracking, activity logging, and performance monitoring
The framework now provides enterprise-level features including:
- Enhanced Base Model: Validation, caching, audit trails, soft deletes, and JSON serialization
- Service Layer: Repository pattern and business logic separation with transaction management
- Security Features: Password hashing, account locking, security audit logging, and risk assessment
- Performance Monitoring: Response time tracking, slow endpoint detection, and resource usage metrics
- Multi-Currency Support: Currency-specific balance management with transaction controls
📖 See MVC_ENHANCEMENTS.md for comprehensive documentation and usage examples.
Potential areas for further development:
- GraphQL API integration
- Real-time notifications with WebSockets
- Advanced search capabilities with Elasticsearch
- Machine learning model integration
- Microservices architecture support
Contributions are welcome! If you'd like to collaborate, feel free to fork this repository and submit a pull request. Potential areas of contribution include:
- Implementing additional Flask features.
- Expanding Discord bot functionalities (commands, event listeners, etc.).
- Integrating new third-party APIs or services.
- Improving the MVC structures
Check out the issues section for current needs, or suggest your own enhancements!
-
Clone the Repository:
git clone https://github.com/zaber-dev/Zeython.git cd Zeython -
Install Dependencies:
pip install -r requirements.txt
-
Set up Environment Variables: Create a
.envfile in the root directory with the required environment variables for Flask and Discord (check the.env-examplefile). -
Run the Application:
python config/boot.py
-
Run in Docker:
docker build -t zeython . docker run -d -p 5000:5000 zeython
This project is licensed under the GNU General Public License v3.0.