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:

```bash
./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:

```bash
./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:

```bash
./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:

```bash
# 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:

```bash
./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