Enhance documentation and setup guides; add MkDocs workflow for deployment

Author: zaber-dev

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'LEARN.md'
+      - 'README.md'
+  workflow_dispatch:
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install MkDocs
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

CONTRIBUTING.md

@@ -114,3 +114,9 @@ If you have any questions or need assistance, feel free to reach out by:
 - Mailing me at: zaber@zealtyro.com
 
 Thank you for helping to improve this project! 😊
+
+---
+
+For a more detailed contributor environment and workflow, see the Developer Setup guide:
+
+- docs/developer-setup.md

LEARN.md

@@ -0,0 +1,93 @@
+# Learn Zeython
+
+Welcome to Zeython! This guide walks you from zero to productive with the modular MVC framework.
+
+Zeython is created by Md Mahedi Zaman Zaber and is the improved, advanced version of MVC-Python.
+
+- Repository: https://github.com/zaber-dev/Zeython
+- License: GPL-3.0-or-later
+
+## Who is this for?
+
+- Python developers who want a clean MVC foundation with services (web, Discord, and more)
+- Teams that value configuration-driven, modular architecture
+- Learners exploring service-oriented application design with Flask
+
+## Quick Start
+
+1) Clone and install
+
+```bash
+git clone https://github.com/zaber-dev/Zeython.git
+cd Zeython
+pip install -r requirements.txt
+```
+
+2) Configure environment
+
+Create a `.env` in the project root (see `.env_example` if present):
+
+```env
+FLASK_HOST=127.0.0.1
+FLASK_PORT=5000
+DATABASE_URL=sqlite:///database.db
+```
+
+3) Run
+
+```bash
+python config/application.py
+```
+
+Open http://127.0.0.1:5000/
+
+## What you’ll build/learn
+
+- MVC structure with clear separation of concerns
+- Service management: register, enable, run in parallel
+- Database layer and models with enhanced features
+- Web routes and APIs, plus optional Discord integration
+
+## Concepts map
+
+- Architecture overview: docs/architecture.md
+- Getting started: docs/getting-started.md
+- Configuration: docs/configuration.md
+- Models and database: docs/models.md, docs/database.md
+- Services: docs/services/web.md, docs/services/discord.md
+- APIs and routes: docs/api.md
+- Advanced topics: docs/authentication.md, docs/file-management.md, docs/vendor-integrations.md,
+  docs/error-monitoring.md, docs/deployment.md, docs/testing.md, docs/faq.md
+  
+    For developers:
+    - docs/developer-setup.md
+    - docs/coding-standards.md
+    - docs/service-development.md
+    - docs/debugging.md
+
+## Recommended path
+
+1. Read docs/getting-started.md
+2. Skim docs/architecture.md
+3. Configure web service and run a local server
+4. Explore docs/models.md and docs/database.md, then add a simple model
+5. Add/modify a route in routes/web.py and a controller
+6. Optional: enable Discord service and add a command
+7. Deploy with Docker (docs/deployment.md)
+
+## Examples
+
+See EXAMPLES.md for end-to-end snippets, including creating custom services.
+
+## Troubleshooting
+
+- Port already in use: change FLASK_PORT or stop the conflicting process.
+- Flask not installed: ensure `pip install -r requirements.txt` succeeded.
+- Database errors: verify DATABASE_URL and that `database/db.py` initializes correctly.
+
+## Next steps
+
+- Explore tests in `tests/` and add your own.
+- Contribute improvements—see CONTRIBUTING.md.
+
+Happy building with Zeython!

README.md

@@ -9,6 +9,12 @@ Zeython is created by **Md Mahedi Zaman Zaber** and is the improved and advanced
 
 Repository: https://github.com/zaber-dev/Zeython
 
+## Documentation
+
+- Start here: [LEARN.md](LEARN.md)
+- Full docs: [docs/index.md](docs/index.md)
+- Developer guide: [docs/developer-setup.md](docs/developer-setup.md)
+
 ## Key Features
 
 ### 🏗️ **Truly Modular Architecture**

docs/api.md

@@ -0,0 +1,26 @@
+# API and Routes
+
+- Web routes are defined in `routes/web.py`
+- API blueprint is defined in `routes/api.py` and registered by the web service
+
+## Adding routes
+```python
+# routes/web.py
+from flask import current_app as app
+
+@app.route('/hello')
+def hello():
+    return 'Hello, Zeython!'
+```
+
+## API blueprint
+```python
+# routes/api.py
+from flask import Blueprint
+
+api = Blueprint('api', __name__)
+
+@api.route('/status')
+def status():
+    return {'ok': True}
+```

docs/architecture.md

@@ -0,0 +1,24 @@
+# Architecture
+
+Zeython follows a modular MVC architecture with a service manager that runs services in parallel.
+
+## High-level
+- Core (interfaces, config, service manager)
+- Services (web/Flask, optional Discord, your plugins)
+- Models (business entities, validation, caching, audit)
+- Controllers (web and service-specific logic)
+- Routes (web and API Blueprints)
+- Resources (templates and static assets)
+
+## Service manager
+- Register service classes
+- Create instances from configuration
+- Start/stop services safely
+- Status/health reporting
+
+## Threads and lifecycle
+- Services extend ThreadedService and run in their own thread
+- is_enabled() gates startup
+- start/stop/join managed via the manager
+
+See EXAMPLES.md for examples and config/application.py for bootstrapping.

docs/authentication.md

@@ -0,0 +1,8 @@
+# Authentication
+
+Covers user authentication, JWT tokens, sessions, and OAuth integration patterns in Zeython.
+
+- Password hashing in Users model
+- Session tracking with device info
+- JWT creation/validation/revocation
+- OAuth provider stubs (Google, GitHub, Discord)

docs/coding-standards.md

@@ -0,0 +1,23 @@
+# Coding Standards
+
+Consistent, readable code helps everyone contribute effectively.
+
+## General
+- Follow PEP 8 style
+- Prefer type hints throughout
+- Small, focused functions
+- Descriptive names; avoid abbreviations
+
+## Project conventions
+- Services extend `ThreadedService`
+- Use `service_manager` to register and manage services
+- Keep routes thin; place logic in controllers/services
+- Models use enhanced base model features
+
+## Errors and logging
+- Raise specific exceptions from `app.Models.error_handling`
+- Log using module-level loggers
+
+## Tests
+- Put tests under `tests/`
+- Cover happy paths and 1-2 edge cases

docs/config-reference.md

@@ -0,0 +1,25 @@
+# Configuration Reference
+
+Comprehensive reference of environment variables and config keys.
+
+## App
+- APP_NAME: Default app display name (default: Zeython)
+- APP_LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)
+
+## Web Service
+- FLASK_HOST: Enables the web service when set (e.g., 0.0.0.0)
+- FLASK_PORT: Port (default: 5000)
+- FLASK_DEBUG: true/false (default: false)
+
+## Discord Service
+- DISCORD_TOKEN: Enables the Discord service
+- DISCORD_PREFIX: Command prefix (default: !)
+
+## Database
+- DATABASE_URL: SQLAlchemy connection string (e.g., sqlite:///database.db)
+
+## Custom Services
+- YOURSERVICE_ENABLED: true/false
+- YOURSERVICE_...: other keys as needed
+
+See `app/Core/config.py` for defaults and helpers (get, set, is_service_enabled, get_service_config).

docs/configuration.md

@@ -0,0 +1,24 @@
+# Configuration
+
+Zeython configuration is environment-driven with safe defaults.
+
+## App settings
+- APP_NAME (default: Zeython)
+- APP_LOG_LEVEL (default: INFO)
+
+## Web service
+- FLASK_HOST (enable when set)
+- FLASK_PORT (default: 5000)
+- FLASK_DEBUG (default: false)
+
+## Discord service (optional)
+- DISCORD_TOKEN (enables Discord service)
+- DISCORD_PREFIX (default: !)
+
+## Database
+- DATABASE_URL (e.g., sqlite:///database.db)
+
+## Service-specific configs
+Use config.get_service_config(name) to retrieve service configs.
+
+See `app/Core/config.py` for resolution order and helpers.