Skip to main content

Development Guidelines Overview

This section provides comprehensive guidelines for developing Asset360 v3, covering coding standards, testing practices, database management, and workflow procedures.

Why Guidelines Matter​

Consistent development practices ensure:

  1. Code Quality: Maintainable, readable, and reliable code
  2. Team Productivity: Less time debugging, more time building
  3. Onboarding: New developers quickly understand conventions
  4. Technical Debt: Prevent accumulation of problematic code
  5. Best Practices: Leverage industry standards and lessons learned

Guidelines Sections​

Coding Standards​

Project Structure​

Database & Migrations​

Testing​

Framework Usage​

Workflow & Integration​

Core Principles​

1. Clean Code​

Write code that is:

  • Self-documenting: Clear names, obvious intent
  • Simple: Solve problems in straightforward ways
  • DRY: Don't repeat yourself
  • SOLID: Follow SOLID principles

2. Type Safety​

Use TypeScript effectively:

  • No any: Always specify types
  • Strict mode: Enable all strict checks
  • Interfaces: Define clear contracts
  • Type inference: Let TypeScript work for you

3. Domain-Driven Design​

Respect domain boundaries:

  • No cross-domain imports: Use dependency injection
  • Clear responsibilities: Each domain has a specific purpose
  • Ubiquitous language: Use domain terminology consistently

4. Test-Driven Development​

Write tests that:

  • Are independent: Don't rely on other tests
  • Test behavior: Not implementation details
  • Are maintainable: Easy to understand and update
  • Provide confidence: Cover critical paths

5. Documentation​

Document through:

  • JSDoc comments: For all public APIs
  • README files: For major components
  • Type definitions: Self-documenting code
  • This documentation: Architecture and patterns

Quick Reference​

File Naming​

service.ts          # Service class
repository.ts       # Repository class
domain.ts          # Domain types and entities
index.ts           # Public exports
service.test.ts    # Service tests

Import Organization​

// 1. External dependencies
import { eq } from "drizzle-orm";
import type { ProductionDBClient } from "../db/client";

// 2. Shared utilities
import { Money } from "@shared/money";

// 3. Local imports
import type { FundEntity } from "./domain";
import { FundRepository } from "./repository";

Constructor Pattern​

export class ServiceName {
  constructor(
    private repository: RepositoryType,
    private optionalService?: OptionalServiceType,
  ) {}
}

Method Documentation​

/**
 * Creates a new fund with validation
 *
 * @param data - Fund creation data
 * @returns Promise resolving to the created fund
 * @throws Error if fund code already exists or validation fails
 */
async createFund(data: CreateFundRequest): Promise<FundEntity> {
  // Implementation
}

Common Mistakes to Avoid​

❌ DON'T​

// Don't use any
function process(data: any) {}

// Don't import across domains
import { FundService } from "../fund/service";

// Don't use var
var count = 0;

// Don't ignore errors
try {
  await someOperation();
} catch (e) {
  // Empty catch block
}

// Don't create transactions (D1 doesn't support them)
await db.transaction(async (tx) => {});

✅ DO​

// Use specific types
function process(data: ProcessInput) { }

// Use dependency injection
constructor(private fundService?: FundService) { }

// Use const/let
const count = 0;

// Handle errors properly
try {
  await someOperation();
} catch (error) {
  console.error('Operation failed:', error);
  throw new Error(`Failed to process: ${error.message}`);
}

// Use sequential operations
const result1 = await db.insert(...);
const result2 = await db.insert(...);

Tools & Configuration​

Required Tools​

  • Node.js: v20 or higher
  • PNPM: For package management
  • TypeScript: v5.6+
  • VSCode: Recommended IDE
  • Vitest: For testing

Configuration Files​

  • tsconfig.json - TypeScript configuration
  • eslint.config.mjs - Linting rules
  • vitest.config.ts - Test configuration
  • drizzle.config.ts - Database configuration
  • wrangler.jsonc - Cloudflare Workers config

VSCode Extensions​

Recommended extensions:

  • ESLint - Linting support
  • Prettier - Code formatting
  • TypeScript Vue Plugin - Enhanced TS support
  • Vitest - Test runner integration

Getting Help​

  1. Check this documentation - Most answers are here
  2. Read the code - Our code is well-documented
  3. Check tests - Tests show usage examples
  4. Ask the team - We're here to help

Contributing​

When adding new features:

  1. Follow these guidelines
  2. Write tests for your code
  3. Document public APIs with JSDoc
  4. Update this documentation if needed
  5. Request code review before merging

Next Steps​

  1. Read Coding Standards
  2. Understand Project Structure
  3. Review Testing Standards
  4. Explore Database Standards
  5. Check framework-specific guides as needed