Kylehub Identity Kit

Unified authentication & branding scaffold for Kylehub projects. Generate consistent full-stack applications with Zitadel OIDC, dark theme UI, and production-ready architecture.

Features

• Zitadel Authentication - Pre-configured OIDC with PKCE flow
• Vite + React 18 - Lightning-fast frontend with TailwindCSS
• Dark Theme - Beautiful violet-accented UI components
• TanStack Query - Configured API client with auth interceptors
• FastAPI Backend - Async Python with JWT validation
• Modular Infrastructure - Choose PostgreSQL, Redis, arq workers
• Docker Ready - Generated docker-compose based on your choices
• AI-Optimized - Generated docs for AI-assisted development

Generated Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Frontend (React SPA)                           │
│   Vite + TypeScript + TailwindCSS + TanStack Query + react-oidc-context     │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      │ REST API + JWT Bearer Token
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           Backend (FastAPI)                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐  │
│  │  Public Routes  │  │ Protected Routes│  │      Service Layer          │  │
│  │  GET /health    │  │  GET /users/me  │  │  Business Logic             │  │
│  │  GET /docs      │  │  Your Routes... │  │  External Integrations      │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
              ┌───────────────────────┼───────────────────────┐
              │                       │                       │
              ▼                       ▼                       ▼
     ┌────────────────┐      ┌────────────────┐      ┌────────────────┐
     │   PostgreSQL   │      │     Redis      │      │   arq Worker   │
     │   (Optional)   │      │   (Optional)   │      │   (Optional)   │
     └────────────────┘      └────────────────┘      └────────────────┘

Quick Start

One-Liner Install

Interactive mode

curl -fsSL https://raw.githubusercontent.com/kylehub/identity-kit/main/install.sh | bash

With arguments

curl -fsSL https://raw.githubusercontent.com/kylehub/identity-kit/main/install.sh | bash -s -- --name my-app --full

Or Clone & Run

git clone https://github.com/kylehub/identity-kit.git
cd identity-kit
./create-project.sh --name my-app

Interactive Prompts

The generator will ask you:

1. Project name - Used for directory and package names
2. Project description - For package.json and pyproject.toml
3. Zitadel domain - Your auth instance (e.g., auth.example.com)
4. Include PostgreSQL? - Adds SQLAlchemy async + Alembic migrations
5. Include Redis? - Adds Redis client and caching utilities
6. Include arq workers? - Adds background job processing

Generated Structure

my-app/
├── frontend/
│   ├── src/
│   │   ├── components/ui/     # Reusable UI components
│   │   ├── hooks/             # Custom React hooks
│   │   ├── lib/               # Auth, API client, utilities
│   │   ├── pages/             # Route pages
│   │   └── styles/            # Global CSS with theme
│   ├── package.json
│   └── ...
├── backend/
│   ├── app/
│   │   ├── api/routes/        # FastAPI route handlers
│   │   ├── core/              # Config, auth, dependencies
│   │   ├── db/                # Database models (if PostgreSQL)
│   │   ├── services/          # Business logic
│   │   └── workers/           # arq jobs (if enabled)
│   ├── pyproject.toml
│   └── ...
├── docker-compose.yml         # Based on your infrastructure choices
├── AI_CONTEXT.md              # Documentation for AI assistants
└── README.md                  # Project-specific readme

Generator Structure

identity-kit/
├── create-project.sh          # Main generator script
├── generator/
│   ├── scripts/
│   │   ├── generate.sh        # Core generation logic
│   │   └── utils.sh           # Helper functions
│   └── templates/
│       ├── frontend/          # React + Vite template files
│       ├── backend/           # FastAPI template files
│       └── infrastructure/    # Docker, configs
└── README.md

Included Components

Frontend (Always Included)

• Button, Card, Input, Dialog, Select, Badge, Alert, Tooltip
• Toast notifications with hook
• Layout with sidebar
• Auth provider, protected routes, auth hook
• API client with token injection
• Dark theme with violet accents

Backend (Always Included)

• JWT validation with JWKS caching
• Health check endpoint
• CORS configuration
• Pydantic settings

Optional: PostgreSQL

• SQLAlchemy async engine
• Base model with timestamps
• Alembic migrations setup
• Database session dependency

Optional: Redis

• Async Redis client
• Connection pooling
• Cache utilities

Optional: arq Workers

• Worker configuration
• Job definitions template
• Startup/shutdown hooks

🔧 Post-Generation Steps

After generating your project:

cd my-app

# 1. Start infrastructure (if any)
docker compose up -d

# 2. Setup backend
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# 3. Setup frontend
cd ../frontend
npm install

# 4. Configure Zitadel
# - Create SPA application in Zitadel Console
# - Copy Client ID to frontend/.env

# 5. Run development servers
# Terminal 1: cd backend && uvicorn app.main:app --reload
# Terminal 2: cd frontend && npm run dev

License

MIT License - see LICENSE for details.

---

Built with 💜 by Kylehub