SaaS Development Guidelines

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.