{"id":48347577,"url":"https://github.com/shahadathhs/ecoroute","last_synced_at":"2026-04-28T03:08:16.160Z","repository":{"id":346103267,"uuid":"1187250780","full_name":"shahadathhs/ecoroute","owner":"shahadathhs","description":"EcoRoute Atlas is a high-performance, AI-driven backend system for global supply chain management, sustainability tracking, and regulatory compliance.","archived":false,"fork":false,"pushed_at":"2026-04-25T13:58:08.000Z","size":112,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T15:24:18.697Z","etag":null,"topics":["chatbot","fastapi","postgresql","python","qdrant","rag","vector"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shahadathhs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T14:09:36.000Z","updated_at":"2026-04-25T13:58:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shahadathhs/ecoroute","commit_stats":null,"previous_names":["shahadathhs/ecoroute"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/shahadathhs/ecoroute","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahadathhs%2Fecoroute","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahadathhs%2Fecoroute/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahadathhs%2Fecoroute/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahadathhs%2Fecoroute/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shahadathhs","download_url":"https://codeload.github.com/shahadathhs/ecoroute/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahadathhs%2Fecoroute/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32364143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"online","status_checked_at":"2026-04-28T02:00:07.250Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","fastapi","postgresql","python","qdrant","rag","vector"],"created_at":"2026-04-05T08:00:42.847Z","updated_at":"2026-04-28T03:08:16.141Z","avatar_url":"https://github.com/shahadathhs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EcoRoute Atlas\n\n[![Python](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/release/python-3140/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-green.svg)](https://fastapi.tiangolo.com)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![semantic-release: python](https://img.shields.io/badge/semantic--release-python-e10079.svg)](https://github.com/python-semantic-release/python-semantic-release)\n\n![Alt](https://repobeats.axiom.co/api/embed/ca0dcdfe1dbf4b738ba57fd0aee7ab1b0fceef1a.svg \"Repobeats analytics image\")\n\n## Table of Contents\n\n- [Overview](#-overview)\n- [Features](#-core-modules)\n- [Architecture](#-technical-architecture)\n- [Documentation](#-documentation)\n- [Quick Start](#-local-development-setup)\n- [Automated Releases](#-automated-releases)\n- [Available Commands](#-available-make-commands)\n- [Development Workflow](#-development-workflow)\n- [Project Structure](#-project-structure)\n- [Security](#-security)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n---\n\n## Overview\n\n**EcoRoute Atlas** is a production-grade, AI-driven backend system for global supply chain management, sustainability tracking, and regulatory compliance. Built exclusively with **Python and FastAPI**, it integrates advanced AI (Atlas) to provide proactive decision support, automated regulatory audits, and carbon footprint optimization.\n\n---\n\n## Core Modules\n- **Identity \u0026 Access Management (IAM)**: Advanced RBAC with multi-tenancy support for global logistics organizations.\n- **Intelligent Compliance (Atlas AI)**: LLM-powered regulatory assistant using RAG (Retrieval-Augmented Generation) for real-time legal audits.\n- **Dynamic Sustainability Tracking**: Automated CO2 footprint calculation based on route telemetry and vehicle health.\n- **Fleet \u0026 Asset Monitoring**: High-frequency IoT data ingestion for real-time diagnostics and proactive maintenance.\n\n---\n\n## Technical Architecture\nThe system is designed as a high-performance **FastAPI** application with a focus on asynchronous processing and modularity.\n\n- **Stack**: Python 3.14+, FastAPI, Pydantic (v2), SQLAlchemy/asyncpg.\n- **Data Layer**:\n  - **PostgreSQL**: Primary store for structured shipments, assets, and user data.\n  - **Qdrant**: High-dimensional vector database for Atlas AI's knowledge retrieval.\n- **AI/LLM**: Integrates with OpenAI/Anthropic or local models (BGE/E5) for embeddings and inference.\n\n---\n\n## API \u0026 RBAC Specification\nThe system implements a detailed Role-Based Access Control model across 7 distinct user roles:\n- `Super Admin`, `Company Admin`, `Logistics Manager`, `Compliance Officer`, `Sustainability Lead`, `Standard Dispatcher`, `Driver`.\n\nFor the full production-grade endpoint specification, see the [API \u0026 RBAC Spec](./docs/API_RBAC_SPEC.md).\n\n---\n\n## Documentation\n- [AI System Architecture (ATLAS.md)](./docs/ATLAS.md)\n- [Vector Flow Documentation (ATLAS_INTEL_FLOW.md)](./docs/ATLAS_INTEL_FLOW.md)\n- [Production Architecture (ECOROUTE_ARCHITECTURE.md)](./docs/ECOROUTE_ARCHITECTURE.md)\n- [Business Requirements (ECOROUTE_BUSINESS_REQUIREMENTS.md)](./docs/ECOROUTE_BUSINESS_REQUIREMENTS.md)\n- [Detailed API Specification (API_RBAC_SPEC.md)](./docs/API_RBAC_SPEC.md)\n- [API Response Standard (API_RESPONSE_STANDARD.md)](./docs/API_RESPONSE_STANDARD.md)\n\n---\n\n## Local Development Setup\n\nThis project uses **uv** for fast package management and **Docker** for infrastructure services.\n\n### Prerequisites\n\n- **Python 3.14+** (project uses modern Python features)\n- **Docker \u0026 Docker Compose** (for PostgreSQL and Qdrant)\n- **uv** (fast Python package manager)\n\n### Step 1: Install uv\n\nInstall uv if you don't have it already:\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n### Step 2: Clone and Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/shahadathhs/ecoroute.git\ncd ecoroute\n\n# Run full setup (creates venv + installs dependencies)\nmake setup\n```\n\n**What `make setup` does:**\n- Creates `.venv` virtual environment using uv\n- Installs all dependencies from `pyproject.toml`\n- Sets up pre-commit hooks for code quality\n- Downloads and installs all packages in seconds\n\n### Step 3: Start Infrastructure Services\n\nStart PostgreSQL and Qdrant in Docker:\n```bash\nmake docker-infra\n```\n\n**This starts:**\n- **PostgreSQL** on `localhost:5432` (user/pass: `postgres/postgres`, db: `ecoroute`)\n- **Qdrant** on `localhost:6333` (vector database for Atlas AI)\n\n**Why this approach?**\n- Your FastAPI app runs locally with hot reload for fast development\n- Infrastructure services run in Docker for consistency\n- Single `.env` file works for both (compose.yaml auto-overrides URLs for Docker)\n\n### Step 4: Run the Application\n\n```bash\nmake dev\n```\n\nThe API will be available at:\n- **API**: http://localhost:8000\n- **Interactive Docs**: http://localhost:8000/docs\n- **ReDoc**: http://localhost:8000/redoc\n\n---\n\n## Automated Releases\n\nThis project uses **python-semantic-release** for fully automated versioning and releases. No manual version bumping required!\n\n### How It Works\n\n1. **Make commits** using [Conventional Commits](#conventional-commits) format\n2. **Push to main** branch\n3. **GitHub Actions** automatically:\n   - Determines version bump based on commits\n   - Updates version in code\n   - Generates changelog\n   - Creates git tag\n   - Creates GitHub release\n   - Uploads distribution files\n\n### Conventional Commits\n\nYour commit messages determine the version bump:\n\n```bash\n# Feature → Minor version bump (1.0.0 → 1.1.0)\ngit commit -m \"feat: add user authentication\"\n\n# Bug fix → Patch version bump (1.0.0 → 1.0.1)\ngit commit -m \"fix: resolve database connection issue\"\n\n# Breaking change → Major version bump (1.0.0 → 2.0.0)\ngit commit -m \"feat: redesign API architecture\n\nBREAKING CHANGE: Remove deprecated endpoints\"\n\n# Other types (no version bump)\ngit commit -m \"docs: update README\"\ngit commit -m \"chore: upgrade dependencies\"\ngit commit -m \"style: format code\"\ngit commit -m \"refactor: improve code structure\"\ngit commit -m \"test: add user tests\"\ngit commit -m \"ci: improve CI workflow\"\n```\n\n### Release Commands\n\n```bash\n# Preview what version will be released (without releasing)\nmake release-dry-run\n\n# Generate/update CHANGELOG.md only\nmake release-changelog\n\n# Actually publish (automated via CI, not for manual use)\nmake release-publish\n```\n\n---\n\n## Available Make Commands\n\n```bash\n# Setup\nmake setup              # Full setup (venv + install + pre-commit)\nmake venv               # Create virtual environment\nmake install            # Install dependencies\nmake reset-venv         # Force reset venv (fix permission issues)\n\n# Running\nmake dev                # Development server with hot reload\nmake dev-verbose        # Development with verbose logging\nmake prod               # Production server (4 workers)\n\n# Code Quality\nmake lint               # Run ruff linter\nmake lint-fix           # Auto-fix linting issues\nmake format             # Format code with black\nmake format-check       # Check if code needs formatting\nmake type-check         # Run mypy type checker\nmake check-all          # Run all quality checks\nmake fix-all            # Fix all auto-fixable issues\n\n# Pre-commit Hooks\nmake pre-commit-install # Install git hooks (runs before commits)\nmake pre-commit-run     # Run all hooks manually\nmake pre-commit-update  # Update hooks to latest versions\n\n# Release Automation\nmake release-dry-run    # Preview next release version\nmake release-changelog  # Generate CHANGELOG.md\nmake release-publish    # Publish release (used by CI)\n\n# Database\nmake migrate-up         # Run database migrations\nmake migrate-down       # Rollback last migration\nmake migration NAME=add_users  # Create new migration\nmake db-shell           # Open PostgreSQL shell\n\n# Docker\nmake docker-infra       # Start DB + Qdrant (development)\nmake docker-prod        # Start full stack (API + DB + Qdrant)\nmake docker-down        # Stop all Docker services\nmake docker-logs        # Show Docker logs\n\n# Utilities\nmake clean              # Clean generated files, venv, caches\nmake shell              # Python shell with app context\nmake logs               # Tail application logs\nmake update             # Update all dependencies\nmake list               # List installed packages\nmake add PKG=requests   # Add new package\nmake add-dev PKG=pytest  # Add dev package\nmake remove PKG=requests # Remove package\nmake freeze             # Update lock file\n\n# CI/CD\nmake ci                 # Run all CI pipeline checks locally\nmake security           # Run security scan (bandit)\nmake info               # Show project information\n```\n\n---\n\n## Development Workflow\n\n### 1. Feature Development\n\n```bash\n# Create a new branch\ngit checkout -b feature/new-feature\n\n# Make changes\nvim app/services/new_feature.py\n\n# Run quality checks (pre-commit hooks run automatically)\nmake fix-all\n\n# Commit with conventional format\ngit add .\ngit commit -m \"feat: add new feature for user management\"\n\n# Push to main to trigger release\ngit push origin feature/new-feature\n# Create PR, merge to main\n# Automatic release!\n```\n\n### 2. Bug Fix\n\n```bash\n# Fix the bug\nvim app/services/bugfix.py\n\n# Check with pre-commit\nmake pre-commit-run\n\n# Commit\ngit commit -m \"fix: resolve timeout issue in API calls\"\n\n# Push → Automatic patch release\ngit push\n```\n\n### 3. Environment Configuration\n\nThe `.env` file contains all configuration:\n```bash\n# Application\nAPP_NAME=EcoRoute Atlas\nENVIRONMENT=development\nDEBUG=true\n\n# Server\nHOST=127.0.0.1\nPORT=8000\n\n# Database (points to localhost for local development)\nDATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/ecoroute\n\n# Qdrant (points to localhost for local development)\nQDRANT_HOST=localhost\nQDRANT_PORT=6333\n\n# Security\nSECRET_KEY=your-secret-key-change-in-production\n\n# CORS (comma-separated origins)\nCORS_ORIGINS=http://localhost:3000,http://localhost:8000\n```\n\n**Note:** When running `make docker-prod`, Docker Compose automatically overrides `DATABASE_URL` and `QDRANT_HOST` to point to Docker services.\n\n---\n\n## Troubleshooting\n\n### Port already in use?\n```bash\n# Check what's using the port\nlsof -i :8000\n# Or use a different port\nPORT=9000 make dev\n```\n\n### Docker containers not starting?\n```bash\n# Check Docker logs\nmake docker-logs\n\n# Restart Docker services\nmake docker-down\nmake docker-infra\n```\n\n### Dependencies not installing?\n```bash\n# Clean and reinstall\nmake clean\nmake setup\n```\n\n### Pre-commit hooks not running?\n```bash\n# Reinstall hooks\nmake pre-commit-install\n\n# Run manually to check\nmake pre-commit-run\n```\n\n### Want to preview next release?\n```bash\nmake release-dry-run\n# Shows: what version will be released and changelog\n```\n\n---\n\n## Project Structure\n\n```\necoroute/\n├── app/\n│   ├── api/              # HTTP routes (thin layer)\n│   ├── core/             # Config, logging, errors\n│   ├── db/               # Database session management\n│   ├── models/           # SQLAlchemy ORM models\n│   ├── schemas/          # Pydantic request/response schemas\n│   ├── services/         # Business logic layer\n│   └── main.py           # Application entry point\n├── docs/                 # Documentation\n├── tests/                # Test suite (future)\n├── .github/workflows/    # CI/CD workflows\n├── pyproject.toml        # Project config \u0026 dependencies\n├── Makefile              # Development automation\n└── README.md\n```\n\n---\n\n## Security\n\n- Automated security scanning with Bandit\n- Pre-commit hooks for code quality\n- Type checking with mypy\n- Linting and formatting enforcement\n- Host configurable (default: localhost only)\n- CORS configuration for API access\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) to get started.\n\n- Read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup\n- Review [SECURITY.md](SECURITY.md) for vulnerability reporting\n- Follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community guidelines\n\n---\n\n## Support\n\n- **Bug Reports**: Open an issue on GitHub\n- **Feature Requests**: Open an issue with the \"enhancement\" label\n- **Questions**: Use GitHub Discussions\n- **Security Issues**: Email shahadathhossensajib732@gmail.com\n\n---\n\n## Star History\n\nIf you find this project useful, please consider giving it a star!\n\n---\n\n**Author**: [Shahadath Hossen Sajib](https://github.com/shahadathhs)\n**Email**: shahadathhossensajib732@gmail.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshahadathhs%2Fecoroute","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshahadathhs%2Fecoroute","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshahadathhs%2Fecoroute/lists"}