SaaS Development Guidelines

Table of Contents

1. Repository Structure
2. Coding Standards
3. Folder Structure
4. File Naming Conventions
5. Git Workflow
6. Branch Naming
7. Commit Message Format
8. Pull Request Process
9. Code Quality & Review
10. Docker & Containerization
11. Environment Management

Repository Structure

Multi-Repository Setup

• Frontend: {project-name}-frontend
• Backend Services: {project-name}-{service-name} (e.g., myapp-auth-service, myapp-user-service)
• Shared Libraries: {project-name}-shared (common types, utilities)
• Infrastructure: {project-name}-infra (Docker configs, deployment scripts)
• Documentation: {project-name}-docs

Coding Standards

TypeScript Configuration

// tsconfig.json (base configuration)
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "noImplicitReturns": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

General Rules

• Language: TypeScript only, no JavaScript files except configuration
• Indentation: 2 spaces (no tabs)
• Line Length: Maximum 100 characters
• Semicolons: Always required
• Quotes: Single quotes for strings, double quotes for JSX attributes
• Trailing Commas: Always in multiline structures
• Import Order: External libraries → Internal modules → Relative imports

ESLint & Prettier Configuration

// .eslintrc.json
{
  "extends": [
    "@typescript-eslint/recommended",
    "prettier"
  ],
  "rules": {
    "@typescript-eslint/explicit-function-return-type": "error",
    "@typescript-eslint/no-explicit-any": "error",
    "prefer-const": "error",
    "no-console": "warn"
  }
}

Folder Structure

Frontend (React) Structure

src/
├── components/           # Reusable UI components
│   ├── common/          # Shared components
│   └── specific/        # Feature-specific components
├── pages/               # Route components
├── hooks/               # Custom React hooks
├── services/            # API calls and external services
├── store/               # State management (Redux/Zustand)
├── types/               # TypeScript type definitions
├── utils/               # Helper functions
├── constants/           # Application constants
├── assets/              # Static files (images, fonts)
└── styles/              # Global styles and themes

Backend (Node.js/Express) Structure

src/
├── controllers/         # Route handlers
├── services/            # Business logic
├── models/              # Database models/schemas
├── middleware/          # Custom middleware
├── routes/              # API routes
├── config/              # Configuration files
├── utils/               # Helper functions
├── types/               # TypeScript interfaces
├── validators/          # Input validation schemas
├── database/            # DB connection and migrations
└── __tests__/           # Test files

File Naming Conventions

General Rules

• Directories: kebab-case (user-service, auth-middleware)
• Files: kebab-case with appropriate extensions
• Components: PascalCase for React components (UserProfile.tsx)
• Hooks: camelCase starting with 'use' (useAuth.ts)
• Utilities: camelCase (dateHelper.ts)
• Constants: SCREAMING_SNAKE_CASE for files (API_ENDPOINTS.ts)

Specific Patterns

• React Components: ComponentName.tsx
• API Controllers: entityName.controller.ts
• Services: entityName.service.ts
• Models: EntityName.model.ts
• Types: entityName.types.ts
• Tests: fileName.test.ts or fileName.spec.ts

Git Workflow

Simplified GitFlow

production    ←── staging    ←── development    ←── feature/bug branches
    ↑              ↑              ↑
    │              │              │
   merge          merge          merge
  (deploy)       (deploy)        only

Branch Structure

• production: Production-ready code
• staging: Pre-production testing
• development: Integration branch for features
• feature/: Feature development
• hotfix/: Critical production fixes

Workflow Rules

1. One-way merges only: feature → development → staging → production
2. No direct commits to development/staging/production
3. All changes must go through Pull Requests
4. Hotfixes can go directly to staging, then to production

Branch Naming

Conventions

• Feature branches: feature/TICKET-123-short-description
• Bug fixes: bugfix/TICKET-456-fix-description
• Hotfixes: hotfix/critical-issue-description
• Chores: chore/update-dependencies

Examples

feature/AUTH-001-implement-jwt-authentication
bugfix/USER-045-fix-profile-update-validation
hotfix/payment-gateway-timeout
chore/upgrade-react-version

Commit Message Format

Conventional Commits Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting)
• refactor: Code refactoring
• perf: Performance improvements
• test: Adding or updating tests
• chore: Build process or auxiliary tool changes

Examples

feat(auth): implement JWT token refresh mechanism

fix(user): resolve profile image upload validation error

docs(api): update authentication endpoint documentation

refactor(database): optimize user query performance

Rules

• Use imperative mood ("add" not "added")
• First line under 50 characters
• Body line length under 72 characters
• Reference ticket numbers in footer

Pull Request Process

PR Requirements

1. Title: Follow conventional commit format
2. Description: Include purpose, changes, and testing notes
3. Linked Issues: Reference relevant tickets
4. Reviewers: Assign at least 2 reviewers
5. Labels: Apply appropriate labels (feature, bugfix, etc.)

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated

Merge Rules

• 2 approvals required for development/staging/production
• 1 approval required for feature branches
• Squash and merge for feature → development
• Create merge commit for development → staging → production
• Delete branch after successful merge

Code Quality & Review

SonarQube Integration

• Quality Gates: Must pass before merge to development
• Coverage Threshold: Maintain existing coverage (no decrease)
• Code Smells: Address major and critical issues
• Duplications: Keep under 3%

Code Review Guidelines

1. Security: Check for vulnerabilities and secrets
2. Performance: Review for potential bottlenecks
3. Maintainability: Ensure code is readable and documented
4. Testing: Verify adequate test coverage
5. Standards: Confirm adherence to coding standards

Review Checklist

• [ ] Code is self-explanatory
• [ ] No hardcoded values or secrets
• [ ] Error handling is appropriate
• [ ] TypeScript types are properly defined
• [ ] Performance considerations addressed
• [ ] Security best practices followed

Docker & Containerization

Dockerfile Standards

# Multi-stage build example
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:18-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
USER node
CMD ["npm", "start"]

Container Naming

• Images: {project-name}-{service-name}:{version}
• Containers: {project-name}-{service-name}-{environment}

Docker Compose Structure

# docker-compose.yml
version: '3.8'
services:
  service-name:
    build: .
    environment:
      - NODE_ENV=${NODE_ENV}
    networks:
      - app-network
    depends_on:
      - postgres

Environment Management

Environment Variables

• Development: .env.development
• Staging: .env.staging
• Production: .env.production

Required Variables

# Database
DB_HOST=
DB_PORT=
DB_NAME=
DB_USER=
DB_PASSWORD=

# Application
NODE_ENV=
PORT=
JWT_SECRET=
API_BASE_URL=

# External Services
REDIS_URL=
LOG_LEVEL=

Secrets Management

• Never commit secrets to repository
• Use environment-specific configuration files
• Encrypt sensitive data in production
• Rotate secrets regularly

---

Enforcement

These guidelines are mandatory for all team members. Automated checks will be implemented to ensure compliance:

• Pre-commit hooks for linting and formatting
• CI/CD pipeline checks for code quality
• Branch protection rules in Bitbucket
• SonarQube quality gates

Questions or suggestions for improvements should be discussed in team meetings and documented as updates to this guide.