From f318708ee082dc5a2a6f455594f0d2802cda11bc Mon Sep 17 00:00:00 2001
From: Navid Filsaraee <nfilsaraee@gmail.com>
Date: Wed, 3 Jun 2026 10:37:10 +0330
Subject: [PATCH] first commit

---
 README.md | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2132058
--- /dev/null
+++ b/README.md
@@ -0,0 +1,139 @@
+# Darano
+
+Multi-service monorepo for the Darano financial/crypto platform.
+
+## Services
+
+| Process | Directory | Stack | Local Port |
+|---------|-----------|-------|------------|
+| `api` | `api/` | Go / Gin (REST gateway) | **8000** |
+| `auth` | `auth/` | Go / gRPC | 8100 |
+| `wallet` | `wallet/` | Go / gRPC | 8200 |
+| `wallet-market` | `wallet/` | Go / gRPC | 8300 |
+| `wallet-alert` | `wallet/` | Go / gRPC | 8400 |
+| `wallet-internal` | `wallet/` | Go / gRPC | 8500 |
+| `wallet-stream` | `wallet/` | Go (background) | — |
+| `admin` | `AdminPanel/` | Python / Django | 8080 |
+| `ui` | `ui/` | TypeScript / Next.js | 3000 |
+
+`api` is the only public-facing HTTP service. All other Go services communicate over gRPC. `AdminPanel` reads Postgres directly.
+
+## Prerequisites
+
+- Go 1.22+
+- Node.js 20+ with Yarn
+- Python 3.11+ with [uv](https://github.com/astral-sh/uv)
+- [air](https://github.com/air-verse/air) — Go hot reload (`go install github.com/air-verse/air@latest`)
+- [buf](https://buf.build/docs/installation) — protobuf code generation
+- [overmind](https://github.com/DarthSim/overmind) or [foreman](https://github.com/ddollar/foreman) — Procfile runner
+- PostgreSQL 16, Redis, RabbitMQ running locally (or via Docker)
+
+## Infrastructure
+
+Start the shared infrastructure (Postgres, Redis, RabbitMQ, MinIO):
+
+```bash
+cd DevOps/dev
+docker compose -f infra-compose.yml up -d
+```
+
+## Running Everything
+
+From the repo root:
+
+```bash
+overmind start
+# or
+foreman start
+```
+
+`air` handles the initial build and restarts Go services on any `.go` file change. Next.js and Django have their own built-in reloaders.
+
+To tail a specific service:
+
+```bash
+overmind connect api
+```
+
+## Building Protos
+
+Each Go service and the UI depend on generated protobuf code. Run this before the first build or after any `.proto` change:
+
+```bash
+# inside each Go service directory
+make build-proto
+
+# inside ui/
+yarn build-proto
+```
+
+## Individual Services
+
+### Go services (`api`, `auth`, `wallet`)
+
+```bash
+make dep        # install tools (buf, air, swag, protoc plugins)
+make build      # generate protos + compile binary
+make dev        # hot reload via air
+make test       # run tests
+```
+
+### Wallet sub-services (separate processes sharing one binary)
+
+```bash
+cd wallet
+make dev-wallet     # wallet  → :8200
+make dev-market     # market  → :8300
+make dev-alert      # alert   → :8400 (alias; use air -c .alert.air.toml)
+make dev-stream     # stream
+```
+
+### AdminPanel
+
+```bash
+cd AdminPanel
+uv run python src/manage.py migrate
+uv run python src/manage.py runserver 0.0.0.0:8080
+```
+
+### UI
+
+```bash
+cd ui
+yarn dev        # starts Next.js on :3000; buf generate runs automatically
+```
+
+## Configuration
+
+Each service reads a TOML config file loaded by `fig`:
+
+| Service | Config file |
+|---------|-------------|
+| `api` | `api/cfg.toml` |
+| `auth` | `auth/cfg.toml` |
+| wallet | `wallet/wallet.cfg.toml` |
+| market | `wallet/market.cfg.toml` |
+| alert | `wallet/alert.cfg.toml` |
+| internal wallet | `wallet/wallet.internal.cfg.toml` |
+| stream | `wallet/cfg.toml` |
+
+The canonical reference for all credential values is `DevOps/services/srv-dev/cfg/fig.toml` (used by Docker deployments).
+
+JWT keys for local dev are read from `DevOps/services/srv-dev/cfg/jwt/`.
+
+## Environment Variables (UI)
+
+`ui/.env.development.local` is pre-configured for local development:
+
+```
+NEXT_PUBLIC_API_URL=http://localhost:8000/
+NEXTAUTH_URL=http://localhost:3000/
+```
+
+## Log Directories
+
+Go services write logs to `./log/` relative to their directory. Create these before first run:
+
+```bash
+mkdir -p api/log auth/log wallet/log
+```