gh_UserManager/README.md

# Identity Platform

**One Identity. Every Product.**

Central identity, authentication, and authorization infrastructure for your product ecosystem. Built as an independent platform — not owned by any single product.

## Quick Start

### Prerequisites
- Docker 27+ and Docker Compose
- Node 20+ (for local frontend dev)
- Python 3.12+ (for local backend dev)

### Run with Docker Compose (Recommended)

```bash
# Copy env and adjust if needed
cp .env.example .env

# Build and start all services
docker compose up --build -d

# Run migrations (first time only)
docker compose exec api python manage.py migrate

# Create superuser (optional)
docker compose exec api python manage.py createsuperuser
```

**Services:**
- Frontend: http://localhost:3000
- API (DRF): http://localhost:8000/api/v1/
- API Docs (OpenAPI/Swagger): http://localhost:8000/api/docs/
- Admin: http://localhost:8000/admin/
- PostgreSQL: localhost:5432
- Redis: localhost:6379

### Local Development (Without Docker)

**Backend:**
```bash
cd apps/api
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp ../../.env.example .env  # adjust DATABASE_URL to sqlite:///dev.db for quick start
python manage.py migrate
python manage.py runserver
```

**Frontend:**
```bash
cd apps/web
npm install
npm run dev
```

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                      IDENTITY PLATFORM                       │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │  Users  │  │   Auth  │  │  Org    │  │ Session │  ...   │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
│       └────────────┴────────────┴────────────┘              │
│                    PRIVATE KEY (RS256)                       │
└────────────────────────────┬────────────────────────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
         ┌─────────┐   ┌─────────┐   ┌─────────┐
         │Bermooda │   │ Hamsoo  │   │  Future │
         │  (ERP)  │   │ (Network)│  │  Apps   │
         └─────────┘   └─────────┘   └─────────┘
              ▲              ▲              ▲
              │   PUBLIC KEY (verify only)  │
              └──────────────┴──────────────┘
```

**Data Ownership Boundary:**
| Data | Owner |
|------|-------|
| User ID (UUID) | Identity |
| Email & Phone | Identity |
| Authentication & Sessions | Identity |
| Organizations & Memberships | Identity |
| Applications & Service Credentials | Identity |
| Employee & Payroll | Bermooda |
| Profile & Resume | Hamsoo |
| Projects & Listings | Product |

## Key Features

- **OAuth 2.0 & OpenID Connect** — Standard authorize/token/refresh with PKCE
- **Sessions & Devices** — Track, revoke remotely, device detection, token rotation
- **Organizations & Memberships** — Unified org model reusable as company, team, workspace
- **Applications & Service Credentials** — Per-product `client_id`/`client_secret` with explicit ownership
- **Security Events & Audit Log** — Every login, logout, revocation recorded
- **Rate Limiting & Brute-force Protection** — Auto-lockout after failed attempts
- **RS256 Signing** — Private key never leaves platform; products verify with public key
- **OIDC Discovery** — `.well-known/openid-configuration` and JWKS endpoints

## Project Structure

```
D:\Projects\UserManager\
├── docker/                    # Dockerfiles
│   ├── Dockerfile.api        # Django + Gunicorn
│   └── Dockerfile.web        # Next.js multi-stage
├── docker-compose.yml         # All services
├── .env.example              # Environment template
├── apps/
│   ├── api/                  # Django 5.2 backend
│   │   ├── config/           # Settings, URLs, WSGI/ASGI
│   │   └── apps/             # 11 modular apps
│   └── web/                  # Next.js 14 frontend
│       ├── app/              # App Router pages
│       ├── components/       # React components
│       └── lib/              # Utilities, content, i18n
└── packages/
    └── shared/               # Shared TS constants/types
```

## API Endpoints (v1)

| Category | Endpoints |
|----------|-----------|
| **Auth** | `POST /auth/login`, `POST /auth/refresh`, `POST /auth/logout` |
| **Users** | `GET /users/me`, `GET /users/{id}` |
| **Organizations** | `GET /organizations`, `POST /organizations`, `GET /organizations/{id}` |
| **Memberships** | `GET /organizations/{id}/memberships`, `POST /organizations/{id}/memberships` |
| **Applications** | `GET /applications`, `POST /applications` |
| **Sessions** | `GET /sessions`, `DELETE /sessions/{id}` |
| **Security** | `GET /events` |
| **OIDC** | `GET /.well-known/openid-configuration`, `GET /.well-known/jwks.json` |

Full OpenAPI spec at `/api/docs/`.

## Environment Variables

Key variables (see `.env.example` for full list):

| Variable | Description |
|----------|-------------|
| `DJANGO_SECRET_KEY` | **Required in production** |
| `DATABASE_URL` | Postgres connection string |
| `REDIS_URL` | Redis connection string |
| `CORS_ALLOWED_ORIGINS` | Frontend origin(s) |
| `NEXT_PUBLIC_SITE_NAME` | Brand name (default: "Identity Platform") |
| `NEXT_PUBLIC_API_URL` | API base URL for frontend |

## Testing

**Backend:**
```bash
cd apps/api
python manage.py test  # 21 tests
```

**Frontend:**
```bash
cd apps/web
npm run build  # TypeScript + ESLint + Next build
```

## Security Notes

- No "military-grade" claims — real security only
- Private RS256 key stays in Identity Platform
- Products hold only public JWKS
- Sessions and refresh tokens revocable instantly
- Rate limits per-user and per-IP
- Security events immutable audit log

## License

Proprietary — Independent business unit within the holding.

---

Built with Django 5.2 + DRF, Next.js 14, PostgreSQL, Redis, Tailwind, TypeScript.