Skip to content

Developer Overview

Welcome to the HKFR development documentation. This section provides comprehensive information for developers working on the HKFR platform.

Architecture at a Glance

HKFR is built as a modern web application with a clear separation between frontend and backend concerns:

graph TB
    subgraph "Frontend"
        A[Next.js 15 App]
        B[React 19 Components]
        C[Tailwind CSS]
    end

    subgraph "Backend"
        D[Next.js API Routes]
        E[JWT Authentication]
        F[File Processing]
    end

    subgraph "Data Layer"
        G[MongoDB]
        H[Google Cloud Storage]
        I[PostgreSQL]
    end

    subgraph "Infrastructure"
        J[Google Kubernetes Engine]
        K[ArgoCD]
        L[Terraform]
    end

    A --> D
    D --> G
    D --> H
    D --> I
    J --> A
    J --> D
    K --> J
    L --> J

Technology Stack

Frontend Technologies

  • Framework: Next.js 15 with App Router
  • UI Library: React 19
  • Styling: Tailwind CSS 4
  • State Management: React built-in state + Context API
  • Type Checking: JavaScript with JSDoc (considering TypeScript migration)

Backend Technologies

  • Runtime: Node.js
  • Framework: Next.js API Routes
  • Authentication: JWT with refresh tokens
  • Password Hashing: bcrypt
  • File Processing: Pandoc, PDFKit, ExcelJS

Database & Storage

  • Primary Database: MongoDB for document storage
  • Relational Data: PostgreSQL via Google Cloud SQL
  • File Storage: Google Cloud Storage
  • Caching: In-memory with potential Redis integration

Development Tools

  • Testing: Vitest with React Testing Library
  • Linting: ESLint with Next.js configuration
  • Code Formatting: Built-in Next.js standards
  • Package Management: npm

Infrastructure & DevOps

  • Cloud Provider: Google Cloud Platform
  • Container Orchestration: Google Kubernetes Engine (GKE)
  • Infrastructure as Code: Terraform + Terragrunt
  • CI/CD: GitHub Actions
  • GitOps: ArgoCD
  • Monitoring: Google Cloud Operations Suite

Project Structure

project-8-chkl/
├── hkfr/                    # Main application
│   ├── src/
│   │   ├── app/             # Next.js App Router
│   │   │   ├── api/         # Backend API endpoints
│   │   │   ├── editor/      # Document editor pages
│   │   │   ├── ui/          # Reusable UI components
│   │   │   └── dashboard/   # Dashboard pages
│   │   ├── utils/           # Utility functions
│   │   └── test/            # Testing utilities
│   ├── public/              # Static assets
│   └── package.json         # Dependencies and scripts
├── infra/                   # Infrastructure code
│   ├── modules/             # Terraform modules
│   └── live/                # Environment configurations
├── devops/                  # Kubernetes manifests
└── docs/                    # Documentation (this site)

Development Philosophy

Code Quality

  • 100% Test Success Rate: All tests must pass
  • Comprehensive Testing: Unit, integration, and API tests
  • Code Reviews: All changes require peer review
  • Automated Linting: ESLint enforces code standards

Security First

  • JWT Authentication: Secure token-based auth
  • Input Validation: All API inputs are validated
  • SQL Injection Protection: Parameterized queries
  • XSS Prevention: Proper output encoding
  • HTTPS Only: All communications encrypted

Performance

  • Next.js Optimization: Built-in performance features
  • Database Optimization: Efficient queries and indexing
  • Caching Strategy: Strategic use of caching
  • Bundle Optimization: Code splitting and tree shaking

API Design Principles

RESTful Architecture

  • Resource-based URLs: /api/manage_files/create
  • HTTP Methods: Proper use of GET, POST, PUT, DELETE
  • Status Codes: Meaningful HTTP response codes
  • JSON Communication: Consistent JSON request/response format

Authentication Flow

sequenceDiagram
    participant C as Client
    participant A as Auth API
    participant DB as Database

    C->>A: POST /api/auth/login
    A->>DB: Validate credentials
    DB->>A: User data
    A->>C: JWT tokens (access + refresh)

    Note over C,A: For protected routes
    C->>A: Request with JWT
    A->>A: Verify token
    A->>C: Protected resource

Development Workflow

Git Workflow

  1. Feature Branches: Create branches from main
  2. Pull Requests: All changes via PR with review
  3. Automated Testing: CI runs tests on every PR
  4. Protected Main: Direct pushes to main are blocked

Release Process

  1. Development: Feature development and testing
  2. Integration: Merge to main branch
  3. CI Pipeline: Automated build and test
  4. Container Build: Docker image creation
  5. ArgoCD Deployment: Automatic deployment to cluster

Key Concepts

Document Structure

{
  _id: ObjectId,
  title: String,
  content: Object,      // Rich text content
  metadata: {
    company: String,
    fiscalYear: String,
    reportType: String
  },
  collaborators: [{
    userId: ObjectId,
    role: String,
    permissions: Array
  }],
  versions: Array,
  createdAt: Date,
  updatedAt: Date
}

Authentication System

  • JWT Access Tokens: Short-lived (15 minutes)
  • Refresh Tokens: Long-lived (7 days)
  • Automatic Refresh: Seamless token renewal
  • Secure Storage: HTTP-only cookies for tokens

File Processing Pipeline

  1. Upload: Files uploaded to Google Cloud Storage
  2. Processing: Convert formats using Pandoc
  3. Integration: Link processed data to documents
  4. Export: Generate PDF/DOCX for download

Getting Started

  1. Setup Environment: Local Development Setup
  2. Understand Architecture: Architecture Deep Dive
  3. API Reference: API Documentation
  4. Testing Guide: Testing Documentation

Contributing Guidelines

Code Standards

  • Follow existing code patterns and conventions
  • Write comprehensive tests for new features
  • Update documentation for API changes
  • Use meaningful commit messages

Pull Request Process

  1. Create feature branch from main
  2. Implement changes with tests
  3. Run full test suite locally
  4. Create PR with detailed description
  5. Address review feedback
  6. Merge after approval

Support and Resources