vibeStonk/.junie/guidelines.md

VibeStonk Development Guidelines

This document provides essential information for developers working on the VibeStonk project.

Build/Configuration Instructions

Prerequisites

• Go 1.23.0 or later
• Node.js and npm (for client development)
• Protocol Buffers compiler (protoc)
• Go Plugin for Protocol Buffers compiler

Project Structure

• client/: Frontend code
• proto/: Protocol Buffer definitions
• server/: Backend Go code
• scripts/: Build and utility scripts
• dist/: Build artifacts
• kubes/: Kubernetes deployment configurations

Building the Project

The project can be built using the provided build script:

./scripts/build.sh

This script:

1. Cleans the dist directory
2. Generates Go code from Protocol Buffer definitions
3. Builds the Go server
4. Builds the client using npm
5. Copies client build artifacts to the dist/content directory

Docker Build

For containerized deployment, use the Docker build script:

./scripts/build_docker.sh

This builds Docker images for both the API server and static content server.

Protocol Buffer Generation

Protocol Buffer code is generated using:

./scripts/generate_proto.sh

This script:

1. Removes old generated files
2. Creates directories for TypeScript definitions
3. Generates Go code from Protocol Buffer definitions
4. Generates TypeScript definitions for client-side use

Configuration

The server uses a configuration system defined in server/repository/config.go. The default configuration can be obtained using repository.GetDefaultConfig(), which sets up:

• Database engine (SQLite)
• Data directories
• Server listen address (0.0.0.0:8080)

Testing Information

Test Configuration

Tests use a separate configuration obtained via repository.GetTestConfigs(), which:

• Uses the "test-data/" directory for test databases
• Creates separate test databases for each supported database engine

Running Tests

Tests can be run using the standard Go test command:

# Run all tests in a package
cd server/util && go test

# Run tests with verbose output
cd server/util && go test -v

# Run a specific test
cd server/util && go test -v -run TestReverseString

Test Cleanup

After running tests, you can clean up test databases using:

./scripts/remove_test_dbs.sh

Creating Tests

Tests follow the standard Go testing pattern:

1. Create a file with the _test.go suffix
2. Import the testing package
3. Create test functions with the Test prefix

Below are examples of tests in this project. Note that these are simplified examples for illustration purposes.

Example of a simple utility test using table-driven testing:

// In file: server/util/string_utils_test.go
package util

import (
    "testing"
)

// TestReverseString tests the ReverseString function
func TestReverseString(t *testing.T) {
    // Define test cases with input and expected output
    testCases := []struct {
        name     string
        input    string
        expected string
    }{
        {"empty string", "", ""},
        {"normal string", "hello", "olleh"},
    }

    // Run each test case
    for _, tc := range testCases {
        t.Run(tc.name, func(t *testing.T) {
            result := ReverseString(tc.input)
            if result != tc.expected {
                t.Errorf("Expected %q, got %q", tc.expected, result)
            }
        })
    }
}

Example of a service test:

// In file: server/services/authService_test.go
package services

import (
    "testing"
    "vibeStonk/server/repository"
    "vibeStonk/server/util"
)

// TestAuthService_RegisterUser tests user registration
func TestAuthService_RegisterUser(t *testing.T) {
    // Get test configurations and credentials
    configs := repository.GetTestConfigs()
    testUserName, testUserPassword := util.GetTestUserCredentials()

    // Test with each configuration
    for _, config := range configs {
        // Create service
        service, err := NewAuthService(config)
        if err != nil {
            t.Errorf("error creating service: %v", err)
        }

        // Register user
        user, err := service.RegisterUser(testUserName, "Test", testUserPassword)
        if err != nil {
            t.Errorf("expected no error, got: %+v", err)
        }

        // Verify user properties
        if user.UserName != testUserName || user.PrefName != "Test" {
            t.Fail()
        }
    }
}

Test Utilities

The project provides test utilities in:

• server/util/testDB.go: Provides test user credentials
• server/repository/config.go: Provides test configurations

Additional Development Information

Code Organization

• Routes: Defined in server/routes/, using the Echo framework
• Services: Business logic in server/services/
• Repository: Data access in server/repository/
• Models: Generated from Protocol Buffers in server/models/
• Utilities: Helper functions in server/util/

API Server

The API server is created using routes.NewAPIServer(config) and routes are added using the AddRoute or AddRoutesBulk methods.

Authentication

The project uses a token-based authentication system:

• Tokens are provided in the "Bearer" header
• Authentication is handled by the AuthenticationMiddleware
• User registration and authentication are managed by the AuthService

Database

The project uses SQLite for data storage:

• Database files are stored in the "data/" directory
• Test databases are stored in the "test-data/" directory
• The database engine is configurable in the Config struct

Error Handling

Errors are propagated up the call stack and wrapped with context using fmt.Errorf("context: %w", err).

Generics

The project uses Go generics for type-safe utility functions, as seen in server/util/func.go and server/util/string_utils.go.

Kubernetes Deployment

The project includes Kubernetes deployment configurations in the kubes/ directory:

• Namespace configuration
• Deployment configurations for API and static content servers
• Service configurations
• Ingress configuration for routing external traffic