Added Procfile for running everything in dev
This commit is contained in:
@@ -0,0 +1,133 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Repository Structure
|
||||
|
||||
This is a multi-service monorepo for the Darano financial/crypto platform. Each subdirectory is its own independent git repository:
|
||||
|
||||
| Directory | Language | Role |
|
||||
|-----------|----------|------|
|
||||
| `api/` | Go | HTTP REST gateway (Gin) — the only public-facing service |
|
||||
| `auth/` | Go | gRPC authorization service — OTP, JWT, permissions, identity |
|
||||
| `wallet/` | Go | gRPC wallet service — assets, transactions, Stellar blockchain, market |
|
||||
| `ui/` | TypeScript/Next.js | Customer-facing frontend |
|
||||
| `AdminPanel/` | Python/Django | Internal admin panel for manual ops |
|
||||
| `proto/` | Protobuf | Central schema definitions shared by all services |
|
||||
| `DevOps/` | Docker Compose | Infrastructure configs (Postgres, Redis, RabbitMQ, MinIO, Traefik) |
|
||||
| `docs/` | MkDocs | Documentation site |
|
||||
|
||||
## Service Communication Architecture
|
||||
|
||||
The `api` gateway is the only HTTP-facing service. It receives REST requests and fans them out to backend gRPC services. All inter-service communication is gRPC using protobuf types defined in `proto/`.
|
||||
|
||||
```
|
||||
Browser/Client → api (REST/HTTP) → auth, wallet, market (gRPC)
|
||||
AdminPanel ──────────────────────→ Postgres directly (bypasses api)
|
||||
```
|
||||
|
||||
The `api/service/main.go` defines `DaranoService` — a single interface that composes all upstream gRPC client interfaces (`AuthorizationServiceClient`, `WalletServiceClient`, `MarketplaceSrvClient`, `AlertSrvClient`, `InternalAuthorizationServiceClient`). Each backend service gets one persistent gRPC connection that auto-reconnects after a 2-minute timeout.
|
||||
|
||||
The wallet binary is multi-tenant: it serves `wallet`, `market`, `alert`, `internal_wallet`, and `stream` sub-services from one binary, selected via CLI subcommand.
|
||||
|
||||
## Protobuf Code Generation
|
||||
|
||||
All services depend on generated code. **Always run `make build-proto` before building any service.** Proto definitions live in `proto/`, but each service has its own `buf.gen.yaml` that controls code generation into `domain/stub/go/`.
|
||||
|
||||
After generation, the Go makefiles strip `omitempty` from all JSON tags in `.pb.go` files — this is intentional and required for correct JSON serialization behavior.
|
||||
|
||||
For the UI, TypeScript types are generated from the same protos into `src/types/stub/`.
|
||||
|
||||
## Commands
|
||||
|
||||
### Go services (`api/`, `auth/`)
|
||||
|
||||
```bash
|
||||
make dep # install buf, protoc plugins, swag, air
|
||||
make build # fmt + proto gen + binary → ./build/main
|
||||
make dev # build + hot reload via air
|
||||
make test # go test ./...
|
||||
./build/main serve --conf ./cfg.toml
|
||||
```
|
||||
|
||||
### Wallet service (`wallet/`)
|
||||
|
||||
The wallet binary hosts multiple sub-services. During development, run each separately:
|
||||
|
||||
```bash
|
||||
make build # proto gen + binary
|
||||
make dev-wallet # hot reload wallet sub-service (.wallet.air.toml)
|
||||
make dev-market # hot reload market sub-service (.market.air.toml)
|
||||
make dev-stream # hot reload stream sub-service (.stream.air.toml)
|
||||
make run-wallet # ./build/main serve wallet -c ./wallet.cfg.toml
|
||||
make run-market # ./build/main serve market -c ./market.cfg.toml
|
||||
make run-internal # ./build/main serve internal_wallet -c ...
|
||||
make run-alert # ./build/main serve alert -c ./alert.cfg.toml
|
||||
make grpc-ui-wallet # open grpcui on port 7210 (localhost:8200)
|
||||
make grpc-ui-market # open grpcui on port 7300 (localhost:8300)
|
||||
```
|
||||
|
||||
### AdminPanel (`AdminPanel/`)
|
||||
|
||||
Uses `uv` for dependency management (pyproject.toml with uv backend):
|
||||
|
||||
```bash
|
||||
uv run python src/manage.py makemigrations && uv run python src/manage.py migrate
|
||||
make run # runserver on 0.0.0.0:8080
|
||||
make dev # watch mode using funzzy
|
||||
make proto # buf generate → proto stubs via betterproto
|
||||
```
|
||||
|
||||
### UI (`ui/`)
|
||||
|
||||
```bash
|
||||
yarn build-proto # generate TS types from protos (required first)
|
||||
yarn dev # Next.js dev server (also runs buf generate)
|
||||
make dev # same, bound to 0.0.0.0:3000
|
||||
yarn lint # ESLint
|
||||
yarn lint:fix # ESLint with auto-fix
|
||||
yarn build # production build (also runs buf generate)
|
||||
```
|
||||
|
||||
## Go Service Layer Pattern
|
||||
|
||||
`auth` and `wallet` both follow the same layered architecture:
|
||||
|
||||
- **`config/`** — TOML config parsed via `fig`. Global singleton `config.Cfg`. All services started with `--conf ./cfg.toml`.
|
||||
- **`domain/stub/go/`** — Generated protobuf Go code. Never edit manually.
|
||||
- **`cmd/`** — Cobra CLI entry points. Cobra subcommands map to different serve modes.
|
||||
- **`repository/`** — Data access. `repository.System` (auth) / `repository.Repository` (wallet) aggregates `IPostgres`, `IRedis`, `IService`, and `IQueue` (wallet only) interfaces.
|
||||
- **`usecase/`** (auth) / **`core/`** (wallet) — Business logic. Implements the gRPC server interfaces defined in proto.
|
||||
- **`util/`** — Shared helpers; no business logic.
|
||||
|
||||
In `auth`, the `usecase.UseCase` interface directly embeds the generated gRPC server interfaces (`authv1.AuthorizationServiceServer`, `authv1.InternalAuthorizationServiceServer`).
|
||||
|
||||
## API Gateway Routing Pattern
|
||||
|
||||
`api/handler/routing.go` organizes all routes into three groups:
|
||||
- `/v1/public/` — no auth required
|
||||
- `/v1/client/` — requires `AuthorizationMiddleware` (JWT validation via auth gRPC service)
|
||||
- `/v1/admin/` — requires `AuthorizationMiddleware` (currently mostly placeholder)
|
||||
|
||||
Handler files in `api/handler/` map 1:1 to domains (`wallet.go`, `market.go`, `authorization.go`, etc.). All handlers call into the `DaranoService` interface and use `MarshalResponse` from `response.go` for consistent output.
|
||||
|
||||
## UI Architecture
|
||||
|
||||
- Next.js App Router under `src/app/`. Auth-protected routes: everything under `/dashboard/` (enforced by `src/middleware.ts` via next-auth).
|
||||
- `src/services/` — plain functions wrapping axios calls to the api gateway, typed with generated protobuf types.
|
||||
- `src/stores/` — Zustand stores for global client state.
|
||||
- `src/hooks/` — TanStack Query hooks built on top of the service functions.
|
||||
- Component library: HeroUI. Styling: Tailwind CSS with RTL support (Persian/Farsi UI).
|
||||
- Formik + Yup for forms; react-hook-form used in some newer components.
|
||||
|
||||
## Infrastructure
|
||||
|
||||
Dev infrastructure via `DevOps/dev/infra-compose.yml`: PostgreSQL 16, Redis, RabbitMQ, MinIO. All services connect to shared infra; each Go service has its own DB name.
|
||||
|
||||
All Go services instrument with Elastic APM (`go.elastic.co/apm`) and expose Prometheus metrics. Traefik handles TLS and routing in production.
|
||||
|
||||
## Configuration
|
||||
|
||||
All Go services use TOML config files loaded by `fig`. The `Peer` struct in each service's `config.go` lists upstream gRPC addresses. Field names in `Peer` must exactly match the `ServicesEnum` string values used for reflection-based URL lookup.
|
||||
|
||||
The `fig` library reads struct tags (`fig:"field-name"`) — use those when adding config fields, not environment variables.
|
||||
@@ -0,0 +1,20 @@
|
||||
# Go services — air builds on first run and rebuilds+restarts on any .go change
|
||||
api: cd api && sleep 2 && air
|
||||
auth: cd auth && air
|
||||
|
||||
# Wallet binary hosts multiple sub-services; each gets its own air config + cfg file.
|
||||
# All five run `make build` independently — Go's build cache serialises concurrent builds safely.
|
||||
wallet: cd wallet && air -c .wallet.air.toml
|
||||
wallet-market: cd wallet && air -c .market.air.toml
|
||||
wallet-alert: cd wallet && air -c .alert.air.toml
|
||||
wallet-internal: cd wallet && air -c .internal.air.toml
|
||||
wallet-stream: cd wallet && air -c .stream.air.toml
|
||||
|
||||
# Django — built-in autoreloader watches .py / .html / .po files and restarts on change
|
||||
admin: cd AdminPanel && .venv/bin/python src/manage.py runserver 0.0.0.0:8080 --traceback
|
||||
|
||||
# Next.js — yarn dev includes HMR out of the box; buf generate runs automatically before dev server
|
||||
ui: cd ui && yarn dev -H 0.0.0.0 -p 3000
|
||||
|
||||
# Mkdocs - Darano and Dezone documnetaitons
|
||||
docs: cd docs && make dev
|
||||
Reference in New Issue
Block a user