first commit

README.md

@@ -0,0 +1,63 @@
+# Urmi
+
+Phase-one CPaaS console skeleton with independently deployable frontend, API, and data infrastructure.
+
+## Modules
+
+- `frontend/` — Vite, React, TypeScript console
+- `backend/` — FastAPI control-plane API
+- `database/` — PostgreSQL bootstrap schema and seed data
+- `docker-compose.yml` — local modular development stack
+
+## Run locally
+
+```bash
+docker compose up --build
+```
+
+- Console: http://localhost:5173
+- API docs: http://localhost:8000/docs
+- API health: http://localhost:8000/health
+
+## Environment configuration
+
+Urmi uses separate env templates for each layer:
+
+| Template | Copy to | When |
+|----------|---------|------|
+| `.env.example` | `.env` | Docker Compose (backend auth + Google OAuth) |
+| `backend/.env.example` | `backend/.env` | Running FastAPI on the host |
+| `frontend/.env.example` | `frontend/.env` | Running Vite on the host |
+
+Full variable reference, flows, and troubleshooting: **[docs/ENVIRONMENT.md](docs/ENVIRONMENT.md)**
+
+Quick start for Compose:
+
+```bash
+cp .env.example .env
+docker compose up --build
+```
+
+Email/password auth works without Google vars. Set `AUTH_SECRET` before any non-local deploy.
+
+## Authentication
+
+Google sign-in requires `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, and this redirect URI in Google Cloud Console:
+
+```text
+http://localhost:8000/api/v1/auth/google/callback
+```
+
+The canonical `user_accounts` table is separate from `password_credentials` and `oidc_identities`. A verified Google identity is linked to an existing user by normalized email, preventing duplicate accounts. Google-first users can add a password from **Console → profile → Sign-in & security**.
+
+Core development starts PostgreSQL, Redis, the backend, and frontend. Optional phase-one infrastructure is isolated behind Compose profiles:
+
+```bash
+docker compose --profile data-plane --profile analytics --profile object-storage up --build
+```
+
+This additionally starts Kafka, ClickHouse, and MinIO (a local S3-compatible store).
+
+## Architectural boundary
+
+The frontend never accesses a database directly. The FastAPI service owns transactional PostgreSQL access. Kafka, ClickHouse, and object storage are available as separate infrastructure modules for data-plane events, analytics, and files as those features are implemented.