From 7fa9867a38d8acec4475b4dd3394ac054f9af324 Mon Sep 17 00:00:00 2001
From: lilly <li@lly.sh>
Date: Sun, 3 May 2026 20:57:13 +0200
Subject: [PATCH] improve project structure for api

---
 .envrc.dist                            |  9 +++++++++
 .gitignore                             |  5 +++++
 README.md                              | 10 ++++++++++
 api/pyproject.toml                     |  9 +++++++++
 api/src/dooris_api/__init__.py         |  8 ++++++++
 api/{main.py => src/dooris_api/app.py} | 10 ----------
 api/uv.lock                            |  2 +-
 7 files changed, 42 insertions(+), 11 deletions(-)
 create mode 100644 .envrc.dist
 create mode 100644 .gitignore
 create mode 100644 api/src/dooris_api/__init__.py
 rename api/{main.py => src/dooris_api/app.py} (90%)
 mode change 100755 => 100644

diff --git a/.envrc.dist b/.envrc.dist
new file mode 100644
index 0000000..09c6b28
--- /dev/null
+++ b/.envrc.dist
@@ -0,0 +1,9 @@
+# integrate this into your own .envrc file with `source_env .envrc.dist`
+
+watch_file api/pyproject.toml \
+	api/uv.lock
+
+export UV_PROJECT=$(realpath ./api)
+uv venv --allow-existing
+uv sync
+
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..bf53948
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+.envrc
+.direnv/
+
+**/__pycache__
+api/dist
diff --git a/README.md b/README.md
index 42befdc..bb04625 100644
--- a/README.md
+++ b/README.md
@@ -9,3 +9,13 @@ Project structure:
 ├── api # Python application interacting with HomeMatic and providing the API.
 └── app # Web UI
 ```
+
+## API Development
+
+Most things should automatically be set up with the included [direnv script](./.envrc.dist) but if you don't use that, take the following steps:
+
+1. Go to the api/ directory
+2. Run `uv venv` to create a python virtual environment
+3. Install all dependencies of the dooris project into that virtual environment with `uv sync`
+4. Run a development server `uv run uvicorn dooris_api:app --reload`
+
diff --git a/api/pyproject.toml b/api/pyproject.toml
index c8d4d3e..e42ce53 100644
--- a/api/pyproject.toml
+++ b/api/pyproject.toml
@@ -8,3 +8,12 @@ dependencies = [
     "simple-openid-connect>=2.4.0",
     "uvicorn>=0.46.0",
 ]
+classifiers = ["Private :: Do Not Upload"]
+
+[project.scripts]
+"dooris-api" = "dooris_api:main"
+
+[build-system]
+requires = ["flit_core >=3.11,<5"]
+build-backend = "flit_core.buildapi"
+
diff --git a/api/src/dooris_api/__init__.py b/api/src/dooris_api/__init__.py
new file mode 100644
index 0000000..87f208b
--- /dev/null
+++ b/api/src/dooris_api/__init__.py
@@ -0,0 +1,8 @@
+from dooris_api.app import app
+
+
+def main():
+    import uvicorn
+    config = uvicorn.Config(app, port=8000, log_level="info")
+    server = uvicorn.Server(config)
+    server.run()
diff --git a/api/main.py b/api/src/dooris_api/app.py
old mode 100755
new mode 100644
similarity index 90%
rename from api/main.py
rename to api/src/dooris_api/app.py
index 5b9331f..186574d
--- a/api/main.py
+++ b/api/src/dooris_api/app.py
@@ -53,13 +53,3 @@ async def login_callback(req: Request, resp: Response):
     else:
         return {"authenticated": False}
 
-
-def main():
-    import uvicorn
-    config = uvicorn.Config(app, port=8000, log_level="info")
-    server = uvicorn.Server(config)
-    server.run()
-
-
-if __name__ == "__main__":
-    main()
diff --git a/api/uv.lock b/api/uv.lock
index de8059d..fc202d9 100644
--- a/api/uv.lock
+++ b/api/uv.lock
@@ -233,7 +233,7 @@ wheels = [
 [[package]]
 name = "dooris-api"
 version = "0.1.0"
-source = { virtual = "." }
+source = { editable = "." }
 dependencies = [
     { name = "fastapi" },
     { name = "simple-openid-connect" },