docs: add architecture documentation and slides

docs/adr/001-use-python-grpc.md

@@ -0,0 +1,18 @@
+# ADR 001: Use Python gRPC for Auth
+
+## Status
+
+Accepted.
+
+## Context
+
+The assessment requires Python with gRPC and focuses on microservice communication.
+
+## Decision
+
+Implement the authentication boundary as an async `grpc.aio` service with protobuf contracts.
+
+## Consequences
+
+Service-to-service calls are strongly typed and efficient. Browser interaction needs a separate demo client service because native browser gRPC is not practical without grpc-web or a proxy.
+

docs/adr/002-redis-otp-state.md

@@ -0,0 +1,18 @@
+# ADR 002: Store OTP State In Redis
+
+## Status
+
+Accepted.
+
+## Context
+
+OTP state is temporary, security-sensitive, and must expire automatically.
+
+## Decision
+
+Store only HMAC hashes of OTP codes in Redis, with TTLs, attempt counters, and request rate limits.
+
+## Consequences
+
+OTP verification is fast and self-expiring. Plaintext OTPs are not persisted. The local debug provider writes a separate development-only key for demos.
+

docs/adr/003-rabbitmq-sms-worker.md

@@ -0,0 +1,18 @@
+# ADR 003: Dispatch SMS Through RabbitMQ
+
+## Status
+
+Accepted.
+
+## Context
+
+SMS providers are external services and can fail or respond slowly.
+
+## Decision
+
+Publish OTP SMS jobs to RabbitMQ and process them in a dedicated worker with manual acknowledgements, retries, and a dead-letter queue.
+
+## Consequences
+
+The auth service remains responsive. SMS delivery is isolated and easier to retry, monitor, and replace.
+

docs/adr/004-sms-provider-strategy.md

@@ -0,0 +1,18 @@
+# ADR 004: Select SMS Providers With Strategy
+
+## Status
+
+Accepted.
+
+## Context
+
+The project supports Kavenegar, SMS.ir, and local debug delivery.
+
+## Decision
+
+Expose a stable `SmsClient` port and choose the concrete provider through a small factory based on `SMS_PROVIDER`.
+
+## Consequences
+
+Adding a new SMS provider does not change the auth use case or worker flow. Tests can mock providers without network access.
+

docs/adr/005-fastapi-demo-client.md

@@ -0,0 +1,18 @@
+# ADR 005: Add FastAPI Demo Client Service
+
+## Status
+
+Accepted.
+
+## Context
+
+The gRPC service needs a simple browser demo for interviews and reviewers.
+
+## Decision
+
+Add `gapido_demo`, a small FastAPI backend-for-frontend that serves static UI and calls the auth service over gRPC.
+
+## Consequences
+
+The demo shows how a separate microservice consumes auth. It remains separate from the auth service package and can be exposed safely through Caddy.
+

docs/adr/006-caddy-production-ingress.md

@@ -0,0 +1,18 @@
+# ADR 006: Use Caddy For Production Ingress
+
+## Status
+
+Accepted.
+
+## Context
+
+Production should expose only the demo UI under `gapido.amiirkhl.ir` with HTTPS.
+
+## Decision
+
+Use Caddy as the reverse proxy and TLS terminator. Route public traffic to `demo-app:8080`.
+
+## Consequences
+
+TLS automation is simple. Internal services remain private on Docker networking.
+

docs/adr/007-compose-overlays.md

@@ -0,0 +1,18 @@
+# ADR 007: Split Local And Production Compose Overlays
+
+## Status
+
+Accepted.
+
+## Context
+
+Local development needs direct access to service ports, while production must expose only Caddy.
+
+## Decision
+
+Keep `docker-compose.yml` private by default, add `docker-compose.local.yml` for local ports, and add `docker-compose.prod.yml` for Caddy and production environment rules.
+
+## Consequences
+
+The same services run locally and on a server, but exposure is controlled by the chosen Compose overlay.
+

docs/adr/README.md

@@ -0,0 +1,10 @@
+# Architecture Decision Records
+
+- [ADR 001: Use Python gRPC for auth](001-use-python-grpc.md)
+- [ADR 002: Store OTP state in Redis](002-redis-otp-state.md)
+- [ADR 003: Dispatch SMS through RabbitMQ](003-rabbitmq-sms-worker.md)
+- [ADR 004: Select SMS providers with Strategy](004-sms-provider-strategy.md)
+- [ADR 005: Add FastAPI demo client service](005-fastapi-demo-client.md)
+- [ADR 006: Use Caddy for production ingress](006-caddy-production-ingress.md)
+- [ADR 007: Split local and production Compose overlays](007-compose-overlays.md)
+