Merge pull request #1 from sdmunozsierra/claude/python-microservice-template-4cLxL

Refactor: modernize project structure with uv, microservices, and CI

Author: sdmunozsierra

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Format check
+        run: uv run ruff format --check src/
+
+      - name: Lint
+        run: uv run ruff check src/
+
+      - name: Type check
+        run: uv run mypy src/myapp/
+
+      - name: Tests
+        run: uv run pytest -v

.gitignore

@@ -3,6 +3,10 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+# Virtual environments
+.venv/
+venv/
+
 # Unit test / coverage reports
 htmlcov/
 .tox/
@@ -15,3 +19,27 @@ coverage.xml
 *.cover
 .hypothesis/
 .pytest_cache/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Runtime data (keep structure, ignore contents)
+data/json/*.json
+data/db/*.db
+data/db/*.db-wal
+data/db/*.db-shm
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

App/main_app.py

@@ -1,8 +1,86 @@
-# barebones-python-module
-Barebones python3 module with testing and logging environment
+# myapp
 
-## Environment
-This repo contains the environment to start coding with an enabled App module (main program), a Logger (logging capabilities), and Tests (using pytest). It has been set up so modules can be imported from anywhere without braking the application.
+A fork-ready, microservice-friendly Python template.
 
-## Settings
-Global settings should be configured in `module_config.py` as it is on the root directory.
+Clone, init, test, run — then extend with your own services.
+
+## Quickstart
+
+```bash
+just init       # install deps, create data dirs, check environment
+just test       # run all tests
+just run        # run the default service
+```
+
+Requires [uv](https://docs.astral.sh/uv/) and [just](https://github.com/casey/just). See `just doctor` for environment checks.
+
+## What You Get
+
+- **uv-native** workflows — `pyproject.toml` as single source of truth, `uv.lock` committed
+- **Microservice architecture** — each service in `src/myapp/services/` with clear boundaries
+- **Typed schemas** — Pydantic models at every boundary, versioned with `schema_version`
+- **Dual persistence** — JSON (atomic file writes) + SQLite (WAL mode), independent by design
+- **CLI** — Click-based, auto-discovers service commands (`project svc <name> <cmd>`)
+- **Optional Streamlit UI** — wraps the same service APIs as the CLI
+- **Quality gates** — ruff, mypy, pytest, all runnable via `just check`
+- **CI** — GitHub Actions running the same gates with uv
+
+## Project Structure
+
+```
+src/myapp/
+├── cli/              # top-level CLI entrypoint
+├── shared/           # config, logging, base schemas, persistence
+│   └── persistence/  # BaseStore, JsonStore, SqliteStore
+└── services/
+    └── example/      # example service (copy to create new ones)
+        ├── api.py        # public interface
+        ├── schemas.py    # I/O models
+        ├── cli.py        # service CLI commands
+        ├── storage/      # JSON + SQLite adapters
+        └── tests/        # service tests
+ui/                   # optional Streamlit app
+data/                 # runtime data (gitignored contents)
+docs/                 # guides and reference
+```
+
+## Commands
+
+```bash
+just --list           # see all available commands
+just init             # bootstrap project
+just doctor           # verify environment
+just fmt              # format code
+just lint             # lint code
+just typecheck        # run mypy
+just test             # run pytest
+just check            # all quality gates
+just run              # run default service
+just cli <args>       # run any CLI command
+just ui               # launch Streamlit
+```
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Quickstart](docs/quickstart.md) | Get running in 3 commands |
+| [Architecture](docs/architecture.md) | Services, boundaries, data flow |
+| [CLI Reference](docs/cli-reference.md) | All commands and options |
+| [Persistence](docs/persistence.md) | JSON vs SQLite, no-sync explained |
+| [Extending](docs/extending.md) | Add services, commands, schemas, UI pages |
+
+## Adding a New Service
+
+```bash
+mkdir -p src/myapp/services/myservice/{storage,tests}
+# Copy and adapt from services/example/
+# The CLI auto-discovers it — no registration needed
+project svc myservice --help
+```
+
+See [Extending](docs/extending.md) for the full walkthrough.
+
+## License
+
+MIT