pre-commit, docs and directory structure bare setup

.editorconfig

@@ -0,0 +1,20 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.py]
+max_line_length = 120
+indent_size = 2
+
+[*.md]
+max_line_length = 120

.gitignore

@@ -9,4 +9,7 @@ wheels/
 # Virtual environments
 .venv
 
-.env
+.env
+
+# Documentation build by MkDocs
+site/

.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-added-large-files

README.md

@@ -1,3 +1,127 @@
 # PyMicroMax
 
 Project about the journey of learning, experimenting, and mastering tech stacks for cloud-native microservices.
+Starting with Python frameworks and tools. Future - add more frameworks and tools.
+
+## Project Structure
+
+```text
+project-root/
+│
+├── microservices/
+│   ├── gateway/        # FastAPI-based API gateway
+│   ├── admin_panel/    # Django-based admin panel
+│   ├── api/            # FastAPI-based public/private APIs
+│   ├── etl/            # Flask-based data pipelines
+│   ├── dashboard/      # Streamlit-based dashboard/visualization
+│
+├── shared/
+│   ├── auth/       # Shared Python libraries (e.g., authentication)
+│   ├── libs/       # Shared Python libraries (e.g., logging)
+│   ├── contracts/  # API contracts (e.g., OpenAPI specs)
+│   ├── models/     # Shared Pydantic/Django models or schema definitions
+│   ├── utils/      # Shared Python libraries (e.g., utilities)
+│
+├── infra/
+│   ├── docker/     # Dockerfiles for services
+│   ├── k8s/        # Kubernetes manifests and Helm charts
+│   ├── iac/        # Terraform IaC for cloud resources
+|   |── config_management /  # TODO:
+│
+├── cicd/           # CI/CD pipelines
+│   ├── .github/
+|       ├── workflows/   # GitHub Actions workflows
+|               ├── ci.yml
+|               ...
+|
+│
+├── docs/           # Documentation for APIs, architecture, workflows
+│
+└── scripts/        # Utility scripts (e.g., for data seeding, setup)
+```
+
+## Web Platform Stack Overview
+
+1. Python Frameworks for Microservices
+   1. Django: For building monolithic or admin panel-based services. Use Django REST Framework (DRF) for API development and Django ORM for interacting with SQL databases.
+   2. Flask: Lightweight framework for creating microservices. Good for smaller services where you don’t need the overhead of Django.
+   3. FastAPI: High-performance framework for APIs. Great for building asynchronous microservices with automatic OpenAPI documentation.
+   4. Streamlit (Optional): For quickly creating data-driven, interactive web apps, suitable for building dashboards.
+2. Database Solutions
+   1. SQL Databases:
+      1. PostgreSQL: Powerful open-source relational database, great for handling complex queries and large datasets.
+      2. MySQL: Another widely used open-source relational database for high-performance applications.
+   2. NoSQL Databases:
+      1. MongoDB: NoSQL database for handling semi-structured data, good for microservices with varying data schemas.
+      2. Redis: For in-memory data storage, caching, and message brokering.
+3. Message Brokers and Event-Driven Communication
+   1. RabbitMQ: Open-source message broker for handling asynchronous tasks and communication between services.
+   2. Apache Kafka: Distributed event streaming platform, useful for high-throughput, fault-tolerant data streaming between microservices.
+4. Containerization and Orchestration
+   1. Docker: For creating containers to run your microservices locally and in the cloud.
+   2. Docker Compose: To manage multi-container Docker applications, ideal for local service orchestration.
+   3. Kubernetes: For orchestrating and managing containerized applications in production (cloud or on-premise).
+      1. Helm: Package manager for Kubernetes, helps with deploying apps and managing Kubernetes resources.
+5. DevOps Tools
+   1. Terraform: For Infrastructure as Code (IaC), managing and provisioning cloud resources (VMs, databases, etc.).
+   2. Ansible: For automating server configuration and deployment tasks.
+   3. CI/CD Tools:
+      1. GitLab CI or GitHub Actions: For automating testing, building, and deployment pipelines.
+      2. Jenkins: Open-source automation server for continuous integration and delivery.
+   4. Prometheus: For monitoring services and creating alerting rules.
+   5. Grafana: For visualizing Prometheus metrics and monitoring microservices.
+6. Authentication and Authorization
+   1. OAuth2 / OpenID Connect: Use OAuth2 for secure API authentication. For managing user roles and permissions, JWT (JSON Web Tokens) is commonly used.
+   2. Authlib: Python library for implementing OAuth2.0 in your applications.
+   3. Keycloak: Open-source Identity and Access Management tool, supports Single Sign-On (SSO) and RBAC.
+7. API Documentation
+   1. OpenAPI/Swagger: Use FastAPI’s automatic OpenAPI generation, or use drf-spectacular for Django.
+   2. Redoc: For presenting your OpenAPI specs in an easily readable format.
+   3. Swagger UI: For testing APIs and generating documentation.
+8. Logging and Monitoring
+   1. ELK Stack (Elasticsearch, Logstash, Kibana): For aggregating, searching, and visualizing logs.
+   2. Fluentd: For log aggregation and forwarding logs to different destinations like Elasticsearch.
+   3. Sentry: For application error monitoring and logging.
+9. Frontend Frameworks
+   1. React or Vue.js: JavaScript libraries for building responsive frontends, useful for dashboards and admin interfaces
+   2. TailwindCSS: A utility-first CSS framework for rapid UI development.
+10. Cloud-Native Transition Tools: For when you transition to the cloud, these tools will allow for a smoother migration from open source to cloud-native services:
+    1. AWS (Amazon Web Services), Azure, or Google Cloud Platform: Start with any provider that offers the services you need for compute, storage, and networking.
+       1. Elastic Kubernetes Service (EKS) or Google Kubernetes Engine (GKE) for Kubernetes orchestration.
+       2. CloudWatch (AWS) or Stackdriver (GCP) for monitoring cloud infrastructure.
+       3. RDS (AWS) or Cloud SQL (GCP) for fully managed databases.
+    2. Serverless Options:
+       1. AWS Lambda or Azure Functions for running code without provisioning servers, great for microservices and event-driven workflows.
+11. Infrastructure Monitoring and Observability
+    1. Jaeger or OpenTelemetry: For distributed tracing, helping to monitor and analyze performance issues in a microservices environment.
+    2. Datadog: Cloud monitoring and observability platform (can also be used for local setups).
+12. Local Development Tools
+    1. Postman: For testing and documenting your APIs locally.
+    2. Docker Desktop: To run Docker containers locally.
+    3. Minikube or K3d or k3s: Lightweight Kubernetes clusters for local development.
+
+## Centralized Authentication
+
+To streamline user authentication across our microservices architecture, we have implemented a centralized authentication service. This service acts as a single point for user authentication, handling user login, token generation, and validation. By centralizing authentication, we ensure a consistent and secure approach to managing user access across all services.
+
+## Additional Authentication for Microservices
+
+While the centralized authentication service provides a robust mechanism for user authentication, each microservice can implement its own additional authentication mechanisms as needed. This allows for specific security requirements or access controls to be enforced at the microservice level, enhancing the overall security posture of our application.
+
+## Git Branching Strategy Overview
+
+The key is to maintain a single repository's branching model where the overall codebase reflects the current development cycle, and each microservice or shared component lives within the same branches.
+
+1. Main Branches:
+   1. `main`: Always production-ready, deployable code.
+   2. `dev`: Active development. All new features and bug fixes are merged here before staging and production.
+2. Feature Branches:
+   1. For each new feature, create a branch like `feature/<feature-name>` where `<feature-name>` is related to the specific feature or change you’re working on (e.g., `feature/service1-auth`).
+   2. These branches will primarily affect the corresponding microservice's directory but can also involve changes in the shared libraries if necessary.
+3. Hotfix Branches:
+   1. For urgent fixes, create a `hotfix/<issue-id>` branch based off the master branch. This is useful for patching live issues.
+4. Release Branches:
+   1. For preparing releases, you can have a branch like `release/<version-number>` which is stable and ready for deployment.
+5. Directory-Specific Considerations:
+   1. Shared libraries (e.g., `shared/auth`): If changes in these shared components affect multiple microservices, feature branches related to these can also exist, such as `feature/shared-auth`.
+   2. Terraform: Infrastructure changes can follow the same process, such as `feature/terraform-update`. This allows you to deploy infrastructure changes in parallel with service features.

docs/about.md

@@ -0,0 +1 @@
+# About the project

docs/index.md

@@ -0,0 +1,8 @@
+# Welcome to PyMicroMax
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

mkdocs.yml

@@ -0,0 +1,8 @@
+site_name: PyMicroMax
+nav:
+  - Home: index.md
+  - About: about.md
+  - Tech Stack: tech_stack.md
+theme:
+    name: mkdocs
+    user_color_mode_toggle: true

pyproject.toml

@@ -5,4 +5,27 @@ version = "0.1.0"
 description = "Project focused on mastering microservices with maximum potential for deployment and scalability."
 readme = "README.md"
 requires-python = ">=3.13"
-dependencies = []
+dependencies = [
+    "mkdocs>=1.6.1",
+]
+
+[dependency-groups]
+dev = [
+    "icecream>=2.1.3",
+    "pre-commit>=4.0.1",
+    "ruff>=0.8.3",
+]
+
+# add config for Ruff to sort imports
+[tool.ruff]
+line-length = 120 # default is 88
+
+[tool.ruff.lint]
+extend-select = ["I",]
+extend-safe-fixes = ["E402", ]
+
+[tool.lint.per-file-ignores]
+"__init__.py" = ["E402"]
+
+[tool.lint.isort]
+force-sort-within-sections = true