startup-starter/skybridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3e3ade75e54b11a8e7c6560b931ecfc88e82bc04
skybridge/CLAUDE.md
Ryan Copley 74b25eba27 -
2025-09-01 17:17:27 -04:00

9.0 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Skybridge is an all-in-one "startup starterpack" monolith application designed to provide everything needed to start a software company with a single platform. Built with a microfrontend architecture, it combines multiple business-critical services including API key management, user authentication, permissions, and a modular plugin system for additional business applications.

Key Technologies:

  • Backend: Go 1.23+ with Gin router, PostgreSQL, JWT tokens
  • Frontend: React 18+ with TypeScript, Mantine UI components
  • Module Federation: Webpack 5 Module Federation for plugin architecture
  • Infrastructure: Podman/Docker Compose, Nginx
  • Security: HMAC token signing, RBAC permissions, rate limiting

Startup Platform Architecture

Business Applications (Microfrontends)

skybridge/
├── kms/                     - API Key Management System
│   ├── [Go backend files]   - Secure token lifecycle management
│   └── web/                 - KMS frontend (port 3002)
├── web/                     - Main Shell Dashboard (port 3000)
├── demo/                    - Plugin Development Template (port 3001)  
├── kms-frontend/           - Legacy KMS interface
└── [future modules]        - Additional business applications

Plugin Architecture (Module Federation)

  • Shell Dashboard (port 3000): Central hub for all business applications
  • KMS Module (port 3002): API key and authentication management
  • Demo Module (port 3001): Template for building new business modules
  • Extensible Design: Easy addition of new business applications (CRM, billing, analytics, etc.)

Backend Architecture (KMS)

cmd/server/          - Application entry point  
internal/            - Go backend core logic
├── domain/          - Domain models and business logic
├── repository/      - Data access interfaces and PostgreSQL implementations  
├── services/        - Business logic layer
├── handlers/        - HTTP request handlers (Gin-based)
├── middleware/      - Authentication, logging, security middleware
├── auth/            - Multiple auth providers (header, JWT, OAuth2, SAML)
└── database/        - Database connection and migrations

Development Commands

Startup Platform Development

# Start complete platform in development mode (run in separate terminals)

# Terminal 1: Main Dashboard Shell
cd web
npm install
npm run dev        # Central dashboard on port 3000

# Terminal 2: KMS Business Module
cd kms/web
npm install  
npm run dev        # API Key Management on port 3002

# Terminal 3: Demo/Template Module
cd demo  
npm install
npm run dev        # Plugin template on port 3001

# Production build
npm run build      # In each business module directory

Platform Backend Development

# Start core platform backend with authentication services
cd kms
INTERNAL_HMAC_KEY=test-hmac-key JWT_SECRET=test-jwt-secret AUTH_SIGNING_KEY=test-signing-key go run cmd/server/main.go

# Build platform backend
go build -o platform-server ./cmd/server

# Run platform tests
go test -v ./test/...

# Test specific business modules
go test -v ./test/ -run TestApplicationCRUD
go test -v ./test/ -run TestStaticTokenWorkflow

Full Platform Deployment (Recommended)

CRITICAL: This project uses podman-compose, not docker-compose.

# Start complete startup platform (database, API, all business modules)
podman-compose up -d

# Start with forced rebuild after code changes  
podman-compose up -d --build

# View platform logs
podman-compose logs -f kms-api-service
podman-compose logs -f postgres

# Stop entire platform
podman-compose down

# Check platform health
curl http://localhost:8081/health

Database Operations

CRITICAL: All database operations use podman exec commands.

# Access database shell
podman exec -it kms-postgres psql -U postgres -d kms

# Run SQL commands via exec
podman exec -it kms-postgres psql -U postgres -c "SELECT * FROM applications LIMIT 5;"

# Check tables
podman exec -it kms-postgres psql -U postgres -d kms -c "\dt"

# Reset test database  
podman exec -it kms-postgres psql -U postgres -c "DROP DATABASE IF EXISTS kms_test; CREATE DATABASE kms_test;"

Key Architecture Patterns

Business Module Plugin System

  • Shell Dashboard (web/webpack.config.js): Central hub consuming all business modules
  • Business Modules (kms/web/webpack.config.js, demo/webpack.config.js): Independent applications exposing functionality
  • Shared Infrastructure: React, Mantine, icons shared across all business modules

Startup Platform Routing

  • Central routing: /app/{businessModule}/* handled by shell dashboard
  • Module autonomy: Each business application handles internal navigation independently
  • Isolated contexts: No React Router conflicts between business modules

Core Authentication System (KMS Module)

The platform's authentication system uses exact permission names (not wildcards):

  • Application management: app.read, app.write, app.delete
  • Token operations: token.read, token.create, token.revoke
  • Repository access: repo.read, repo.write, repo.admin
  • Permission management: permission.read, permission.write, permission.grant, permission.revoke

Business Application Types

Valid application configurations for the platform:

  • "static" - Service-to-service authentication for business modules
  • "user" - User authentication for startup team members

Ownership Models

Platform supports different ownership structures:

  • "individual" - Individual founder/employee ownership
  • "team" - Team/department ownership

Important Development Notes

Business Module Development

  • Port allocation: Dashboard:3000, Demo:3001, KMS:3002, [Future modules:3003+]
  • Environment variables: All business modules require webpack.DefinePlugin for process.env
  • Shared dependencies: Must match versions across all business modules
  • Navigation: Use window.history.pushState() and custom events for inter-module routing
  • Local Development: Do not start webpack microfrontends as they are already running locally

Platform API Integration

  • Base URL: http://localhost:8080 (development)
  • Authentication: Header-based with X-User-Email: admin@example.com
  • Duration format: Convert human-readable formats like "24h" to seconds (86400) for API
  • Permission validation: Use exact permission names from database, not wildcards

Startup Platform UI Standards

  • UI Framework: Mantine v7.0.0 (consistent across all business modules)
  • Icons: Tabler Icons React (shared icon system)
  • Forms: Mantine Form with validation (standardized form handling)
  • Notifications: Mantine Notifications (unified notification system)

Critical Platform Configuration

# Platform Backend Environment Variables (Required)
INTERNAL_HMAC_KEY=<secure-hmac-key-32-chars-min>
JWT_SECRET=<secure-jwt-secret-32-chars-min>  
AUTH_SIGNING_KEY=<secure-auth-key-32-chars-min>

# Platform Database
DB_HOST=postgres  # Use 'postgres' for containers
DB_PORT=5432
DB_NAME=kms
DB_USER=postgres  
DB_PASSWORD=postgres

# Startup Platform Authentication
AUTH_PROVIDER=header
AUTH_HEADER_USER_EMAIL=X-User-Email

Testing & Debugging

  • Platform E2E Tests: ./kms/test/e2e_test.sh for core authentication system
  • Test Users: admin@example.com, test@example.com, limited@example.com
  • Service Ports: API:8080, Nginx:8081, Dashboard:3000, DB:5432
  • Debug Business Modules: Check browser network tab for remoteEntry.js loading from each module

Build & Deployment

  • Development: Run dashboard shell + all business modules + platform backend
  • Container Issues: Use podman-compose build --no-cache if changes don't appear
  • Module Federation: All business modules must be running for dashboard to load them
  • Production: Build all business modules and serve via nginx with proper CORS headers

Security Considerations

  • All platform tokens use HMAC signing with secure keys
  • Permission validation at both API and UI levels across all business modules
  • Rate limiting and comprehensive audit logging for startup compliance
  • CORS configured for secure business module communication
  • Never commit secrets or API keys to repository

Adding New Business Modules

To extend the startup platform with new business applications (CRM, billing, analytics, etc.):

  1. Create new module directory following the pattern of demo/ or kms/web/
  2. Configure Module Federation in webpack.config.js to expose the module
  3. Update shell dashboard (web/webpack.config.js) to consume the new remote
  4. Add to navigation in web/src/components/Navigation.tsx
  5. Follow UI standards using Mantine components and shared dependencies
  6. Implement authentication using the platform's permission system
  7. Test integration ensuring the module loads properly in the dashboard