updated docs strings and added README.md

README.md

@@ -0,0 +1,96 @@
+# openapi_first
+
+# Summary
+
+FastAPI OpenAPI First — strict OpenAPI-first application bootstrap for FastAPI.
+
+FastAPI OpenAPI First is a **contract-first infrastructure library** that
+enforces OpenAPI as the single source of truth for FastAPI services.
+
+The library removes decorator-driven routing and replaces it with
+deterministic, spec-driven application assembly. Every HTTP route,
+method, and operation is defined in OpenAPI first and bound to Python
+handlers explicitly via `operationId`.
+
+---
+
+# Installation
+
+Install using pip:
+
+```bash
+pip install openapi-first
+```
+
+Or with Poetry:
+
+```bash
+poetry add openapi-first
+```
+
+---
+
+# Quick Start
+
+Minimal OpenAPI-first FastAPI application:
+
+```python
+from openapi_first import app
+import my_service.routes as routes
+
+api = app.OpenAPIFirstApp(
+    openapi_path="openapi.yaml",
+    routes_module=routes,
+    title="My Service",
+    version="1.0.0",
+)
+```
+
+OperationId-driven HTTP client:
+
+```python
+from openapi_first.loader import load_openapi
+from openapi_first.client import OpenAPIClient
+
+spec = load_openapi("openapi.yaml")
+client = OpenAPIClient(spec)
+
+response = client.get_health()
+```
+
+---
+
+# Architecture
+
+The library is structured around four core responsibilities:
+
+- `loader`: Load and validate OpenAPI 3.x specifications (JSON/YAML).
+- `binder`: Bind OpenAPI operations to FastAPI routes via `operationId`.
+- `app`: OpenAPI-first FastAPI application bootstrap.
+- `client`: OpenAPI-first HTTP client driven by the same specification.
+- `errors`: Explicit error hierarchy for contract violations.
+
+---
+
+# Public API
+
+The supported public API consists of the following top-level modules:
+
+- `openapi_first.app`
+- `openapi_first.binder`
+- `openapi_first.loader`
+- `openapi_first.client`
+- `openapi_first.errors`
+
+---
+
+# Design Guarantees
+
+- OpenAPI is the single source of truth.
+- No undocumented routes can exist.
+- No OpenAPI operation can exist without a handler or client callable.
+- All contract violations fail at application startup or client creation.
+- No hidden FastAPI magic or implicit behavior.
+- Deterministic, testable application assembly.
+
+---