From 0283020903317f42f774ea79a3e05b3d233c9b7c Mon Sep 17 00:00:00 2001
From: Bedram Tamang <tmgbedu@gmail.com>
Date: Fri, 3 Jul 2026 09:15:23 -0700
Subject: [PATCH] docs: add Codecov coverage badge to core package README

Create fastapi_startkit/README.md with a live Codecov badge and
configure CI to collect coverage (--cov --cov-report=xml) and upload
the report to Codecov via codecov-action.
---
 .github/workflows/test.yml | 11 ++++++-
 fastapi_startkit/README.md | 61 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 1 deletion(-)
 create mode 100644 fastapi_startkit/README.md

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 5b26fc1c..0ff8ceaa 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -43,7 +43,16 @@ jobs:
 
             -   name: Run tests (fastapi_startkit)
                 working-directory: fastapi_startkit
-                run: uv run pytest tests/ -v
+                run: uv run pytest tests/ -v --cov --cov-report=xml
+
+            -   name: Upload coverage to Codecov
+                uses: codecov/codecov-action@v5
+                with:
+                    token: ${{ secrets.CODECOV_TOKEN }}
+                    slug: fastapi-startkit/fastapi-startkit-modules
+                    files: fastapi_startkit/coverage.xml
+                    flags: fastapi_startkit
+                    fail_ci_if_error: false
 
             # ── example/config-app ────────────────────────────────────────────────
             -   name: Install dependencies (config-app)
diff --git a/fastapi_startkit/README.md b/fastapi_startkit/README.md
new file mode 100644
index 00000000..b8dabca2
--- /dev/null
+++ b/fastapi_startkit/README.md
@@ -0,0 +1,61 @@
+# FastAPI Startkit
+
+[![codecov](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-modules/graph/badge.svg)](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-modules)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-startkit.svg)](https://pypi.org/project/fastapi-startkit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-startkit.svg)](https://pypi.org/project/fastapi-startkit/)
+
+A modular, provider-driven framework for building Python applications with FastAPI. It bundles a
+service container, configuration system, an async-first ORM, facades, and a Cleo-powered console into
+a single cohesive foundation.
+
+## Installation
+
+```bash
+pip install fastapi-startkit
+```
+
+Optional extras enable additional capabilities:
+
+```bash
+fastapi-startkit[fastapi]    # FastAPI + Starlette
+fastapi-startkit[database]   # SQLAlchemy async ORM
+fastapi-startkit[postgres]   # asyncpg driver
+fastapi-startkit[sqlite]     # aiosqlite driver
+fastapi-startkit[mysql]      # aiomysql driver
+fastapi-startkit[vite]       # Jinja2 for Vite integration
+```
+
+## Features
+
+- **Service container** — IoC container with `bind`/`make`/`resolve` auto-wiring and lifecycle hooks.
+- **Configuration** — dataclass-based config sourced from the environment with dotted-key access.
+- **Providers** — two-phase (`register` / `boot`) service registration.
+- **Routing** — a `Router` wrapper around FastAPI's `APIRouter` with a `resource()` CRUD shortcut.
+- **ORM** — async-first Masonite ORM fork on SQLAlchemy async, with relationships and migrations.
+- **Facades** — static-like access to container-resolved services (`Config`, `Auth`, ...).
+- **Console** — Cleo-based CLI (`artisan`) for migrations, seeders, and code generation.
+
+## Documentation
+
+Full documentation is available at
+[fastapi-startkit.github.io](https://fastapi-startkit.github.io).
+
+## Development
+
+```bash
+# Install dependencies
+uv sync --group dev --extra database --extra sqlite --extra fastapi --extra vite --extra postgres
+
+# Run the test suite
+uv run pytest tests/ -v
+
+# Run tests with coverage
+uv run pytest --cov --cov-report=term-missing
+```
+
+Coverage is collected in CI and reported to
+[Codecov](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-modules).
+
+## License
+
+See the repository root for license details.