Skip to content

README.md

Latest commit

 

History

History
200 lines (140 loc) · 8 KB

README.md

File metadata and controls

200 lines (140 loc) · 8 KB

Datum Cloud Portal Documentation

Welcome to the Datum Cloud Portal developer documentation. This guide will help you get up to speed with the codebase and start contributing.

Quick Start

New to the project? Start here:

  1. Prerequisites - Required tools and access
  2. Environment Setup - Configure your local environment
  3. Running Locally - Start the development server
  4. First Steps - Hands-on exercises

Documentation Overview

📚 Getting Started

Step-by-step guides to get you productive:

Document Description
Prerequisites Tools, versions, and access needed
Environment Setup .env configuration and variables
Running Locally Development server and scripts
First Steps Hands-on exercises and checkpoints

🏗️ Architecture

Understand how the system works:

Document Description
Overview Tech stack and design principles
Data Flow SSR, React Query, and mutations
Domain Modules Resource module structure
Watch API Real-time updates via SSE
ADRs Architecture Decision Records

💻 Development

Day-to-day development tasks:

Document Description
Project Structure Folder organization and imports
OpenAPI Generation Generating typed API clients
Authentication OIDC flow and session handling
Testing E2E and component testing
Code Quality Linting, formatting, TypeScript

🎨 UI Components

Component library and patterns:

Document Description
Overview Component hierarchy and decisions
shadcn Rules Using shadcn/ui primitives
datum-ui Guide Datum component library
Theming Theme system and customization
Forms Form library patterns

⚙️ Operations

Deployment and monitoring:

Document Description
Observability Logging, tracing, metrics
Deployment Docker, Kubernetes, CI/CD
Troubleshooting Common issues and solutions

📖 Guides

How-to guides for common tasks:

Document Description
Adding a New Page Create routes and pages
Adding a New Resource K8s resource integration
Adding a New Module Feature module structure
Adding a New Component Component creation patterns
Debugging Guide Debugging tools and techniques

Tech Stack

Layer Technology
Runtime Bun
Framework React Router v7
Server Hono
State TanStack Query
UI shadcn/ui + Tailwind CSS
Forms Conform + Zod
API OpenAPI with @hey-api/openapi-ts

Key Concepts

Domain-Driven Resources

Resources (DNS Zones, Projects, etc.) follow a modular pattern:

app/resources/{resource}/
├── schema.ts    # Zod validation
├── adapter.ts   # API → Domain transformation
├── service.ts   # API client
├── queries.ts   # React Query definitions
└── watch.ts     # Real-time subscriptions

→ Learn more

Component Hierarchy

features/        → Feature-specific components
components/      → Shared app components
datum-ui/        → Design system (cross-portal)
shadcn/          → UI primitives

→ Learn more

Real-Time Updates

The portal uses SSE (Server-Sent Events) for real-time K8s resource updates:

watchResources({
  onEvent: (event) => {
    // ADDED, MODIFIED, DELETED
    updateCache(event);
  },
});

→ Learn more

Common Tasks

Adding a Feature

  1. Create resource module: Adding a New Resource
  2. Create feature module: Adding a New Module
  3. Create routes: Adding a New Page

Debugging Issues

  1. Check Troubleshooting for common issues
  2. Use Debugging Guide for tools
  3. View traces in Observability

Understanding the Codebase

  1. Start with Architecture Overview
  2. Review Data Flow
  3. Explore Project Structure

Architecture Decision Records

Important architectural decisions are documented as ADRs:

ADR Title
ADR-001 Domain-Driven Resource Modules
ADR-002 Service Adapter Pattern
ADR-003 Query Factory Pattern
ADR-004 Watch API Pattern

→ All ADRs

Getting Help

  • Issues: Report bugs or request features on GitHub
  • Questions: Reach out to the team on Slack
  • PRs: Follow the contribution guidelines

Contributing

  1. Read the Code Quality guidelines
  2. Follow the component patterns in UI docs
  3. Write tests as described in Testing
  4. Ensure CI passes before requesting review