Generate Python Microservices: Project Structure

Python generation creates independently buildable service and Module packages joined by root uv-based automation.

When to use

Use this reference when generating, reviewing or operating a Service Architect project.

Behavior

The root pyproject.toml and uv.lock pin the generated Python workspace.
Each service uses a src layout whose package name is derived from Service.name.
src/<service-package>/main.py starts the service.
src/<service-package>/internal/app contains generated graph assembly, while internal/functions contains preserved business implementations.
Referenced user-defined Modules become independent Python packages containing only the public types, functions, OpenAPI, or protobuf artifacts selected by graph references.

Run a complete Python microservice example

uv packages, typed Python business functions and asyncio-based execution.

The runnable Python example contains business implementations as well as generated infrastructure. A new Designer archive provides extension points for your own business code.

Install Git, GNU Make, Docker with Compose v2, and the host toolchain required by the repository README. Run these commands from the example workspace root; make help lists the targets available in that version.

git clone https://github.com/gorundebug/pyexample.git
cd pyexample
make help
make init
make docker-up

Use the service README and generated configuration for endpoint addresses and example requests.
When finished, make docker-down stops the stack while preserving its volumes.
Continue with the visual design guide or safe regeneration.

Python service directories

Important paths in each generated Python service.

PathOwnershipDescription

pyproject.tomlManaged

Package metadata, dependencies, tools, and service entrypoint.

src/<service-package>/main.pyGenerated entrypoint

Starts configuration and the ServiceLib runtime.

src/<service-package>/internal/app/Generated

Runtime graph, connector, endpoint, and lifecycle assembly.

src/<service-package>/internal/functions/Preserved

Business operators and endpoint handlers.

src/<service-package>/internal/config/Mixed

Generated typed configuration and custom extensions.

src/<service-package>/models/Mixed

Service-local model and serde code.

tests/Preserved + support

Business tests and generated test support.

Dockerfile + Dockerfile.localManaged

Standalone runtime and development images.

Python service tree

<service-name>/
  pyproject.toml
  src/<service-package>/main.py
  src/<service-package>/internal/app/
  src/<service-package>/internal/functions/
  src/<service-package>/internal/config/
  src/<service-package>/models/
  tests/ + config/ + graph/ + docs/
  grafana/ + helm/