📐 Technology Standards and Best Practices¶

Overview¶

This document establishes technology standards, coding conventions, and best practices to ensure consistency, maintainability, and quality across the GetCimple platform.

Technology Stack Standards¶

Frontend Standards¶

SvelteKit Framework¶

Version: Latest stable (5.x)
Configuration: Strict TypeScript mode
Adapter: Cloudflare Workers
Package Manager: pnpm

TypeScript Configuration¶

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowJs": false,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

CSS/Styling Standards¶

Framework: Tailwind CSS v3.x
Component Library: shadcn-svelte
Methodology: Utility-first
Custom Properties: CSS variables for theming

Backend Standards¶

Cloudflare Workers¶

Runtime: Latest Workers runtime
Language: TypeScript only
API Style: RESTful JSON
Validation: Zod schemas

Database Standards¶

Platform: Supabase (PostgreSQL 15+)
Naming: snake_case for tables/columns
Primary Keys: UUID v4
Timestamps: created_at, updated_at

Coding Conventions¶

TypeScript/JavaScript¶

Naming Conventions¶

// Constants: UPPER_SNAKE_CASE
const MAX_RETRY_ATTEMPTS = 3;

// Classes: PascalCase
class UserService {}

// Interfaces/Types: PascalCase with 'I' prefix for interfaces
interface IUserData {}
type UserRole = 'admin' | 'user';

// Functions/Methods: camelCase
function getUserById(id: string) {}

// Variables: camelCase
const userName = 'John';

// Private properties: underscore prefix
private _internalState = {};

// Boolean variables: is/has/should prefix
const isActive = true;
const hasPermission = false;

Code Organization¶

// Import order
import { external } from 'package' // 1. External packages
import { internal } from '$lib/utils' // 2. Internal aliases
import { Component } from './Component' // 3. Relative imports
import type { Type } from './types' // 4. Type imports

// File structure
// 1. Imports
// 2. Type definitions
// 3. Constants
// 4. Main code
// 5. Helper functions
// 6. Exports

Svelte Components¶

Component Structure¶

<script lang="ts">
    // 1. Imports
    import { onMount } from 'svelte';

    // 2. Props
    export let title: string;
    export let visible = true;

    // 3. State
    let count = 0;

    // 4. Reactive declarations
    $: doubled = count * 2;

    // 5. Lifecycle
    onMount(() => {
        // initialization
    });

    // 6. Functions
    function increment() {
        count += 1;
    }
</script>

<!-- Template -->
<div class="component">
    <!-- content -->
</div>

<!-- Styles (if needed) -->
<style>
    /* component styles */
</style>

SQL Conventions¶

Table Design¶

-- Tables: plural, snake_case
CREATE TABLE users (
    -- Primary key: always 'id'
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),

    -- Foreign keys: table_id
    tenant_id UUID REFERENCES tenants(id),

    -- Fields: snake_case
    email_address TEXT NOT NULL,
    is_active BOOLEAN DEFAULT true,

    -- Timestamps: always include
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Indexes: idx_table_columns
CREATE INDEX idx_users_email ON users(email_address);

-- Constraints: table_field_constraint
ALTER TABLE users
ADD CONSTRAINT users_email_unique UNIQUE (email_address);

API Design Standards¶

RESTful Endpoints¶

// Resource naming: plural nouns
GET    /api/users           // List
GET    /api/users/:id       // Get one
POST   /api/users           // Create
PUT    /api/users/:id       // Update (full)
PATCH  /api/users/:id       // Update (partial)
DELETE /api/users/:id       // Delete

// Nested resources
GET    /api/tenants/:tenantId/users
POST   /api/users/:userId/roles

Response Format¶

// Success response
{
    "data": {
        "id": "123",
        "type": "user",
        "attributes": {}
    },
    "meta": {
        "timestamp": "2024-01-01T00:00:00Z"
    }
}

// Error response
{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid input",
        "details": [
            {
                "field": "email",
                "message": "Invalid email format"
            }
        ]
    }
}

Testing Standards¶

Test File Naming¶

Unit tests: *.test.ts
Integration tests: *.integration.test.ts
E2E tests: *.e2e.ts

Test Structure¶

describe('UserService', () => {
  describe('getUserById', () => {
    it('should return user when found', async () => {
      // Arrange
      const userId = '123'
      const expectedUser = { id: userId, name: 'Test' }

      // Act
      const result = await service.getUserById(userId)

      // Assert
      expect(result).toEqual(expectedUser)
    })

    it('should throw when user not found', async () => {
      // Test implementation
    })
  })
})

Documentation Standards¶

Code Documentation¶

/**
 * Retrieves a user by their ID
 * @param userId - The unique identifier of the user
 * @returns The user object if found
 * @throws {NotFoundError} When user doesn't exist
 * @example
 * const user = await getUserById('123');
 */
export async function getUserById(userId: string): Promise<User> {
  // Implementation
}

README Structure¶

Project title and description
Quick start guide
Prerequisites
Installation steps
Usage examples
API documentation
Contributing guidelines
License information

Security Standards¶

Input Validation¶

Always validate input with Zod
Sanitize user-generated content
Use parameterized queries
Implement rate limiting

Authentication¶

Use secure session management
Implement proper RBAC
Token expiration policies
Secure password requirements

Performance Standards¶

Frontend Performance¶

Lighthouse score > 90
First Contentful Paint < 1.5s
Time to Interactive < 3.5s
Bundle size limits enforced

Backend Performance¶

API response time < 200ms
Database queries < 50ms
Worker memory < 128MB
Cold start time < 50ms

Version Control Standards¶

Commit Messages¶

type(scope): subject

body (optional)

footer (optional)

Examples:
feat(auth): add two-factor authentication
fix(dashboard): resolve data loading issue
docs(api): update endpoint documentation

Branch Naming¶

Feature: feat/description
Bugfix: fix/description
Docs: docs/description
Refactor: refactor/description

Monitoring Standards¶

Logging¶

Use structured logging
Include correlation IDs
Log levels: ERROR, WARN, INFO, DEBUG
Sensitive data redaction

Metrics¶

Response time percentiles
Error rates by endpoint
Business metric tracking
Resource utilization

Future Standards¶

GraphQL schema design
WebSocket implementation
Microservices patterns
Event-driven architecture