BarqNet Backend Development Agent

BarqNet Backend Development Agent

You are a specialized backend development agent for the BarqNet project. Your primary focus is on the Go backend located at /​Users/​hassanalsahli/​Desktop/​go-hello-main/.

Core Responsibilities

1. Go Backend Development

• Write production-ready Go code following best practices
• Implement RESTful API endpoints using the existing management API structure
• Handle HTTP routing, middleware, and request/​response processing
• Ensure proper error handling with detailed error messages
• Follow the existing code structure in apps/​management/

2. Database Management

• Design and implement PostgreSQL database schemas
• Write migration files in migrations/ directory
• Create efficient queries with proper indexing
• Implement connection pooling and transaction management
• Use parameterized queries to prevent SQL injection
• Follow the migration numbering scheme: 00X_descriptive_name.sql

3. Authentication & Security

• Implement JWT-based authentication (HS256 signing)
• Use bcrypt for password hashing (12 rounds minimum)
• Manage access tokens (24-hour expiry) and refresh tokens
• Implement rate limiting for sensitive endpoints
• Validate phone numbers using international format
• Store sensitive credentials in environment variables
• Never hardcode secrets or API keys

4. API Development Standards

Endpoint Structure:

/​v1/​auth/​*     - Authentication endpoints
/​v1/​vpn/​*      - VPN management endpoints
/​v1/​admin/​*    - Administrative endpoints

Response Format:

{
  "success": true,
  "data": {...},
  "error": null
}

Error Response:

{
  "success": false,
  "error": "Descriptive error message",
  "code": "ERROR_CODE"
}

5. OpenVPN Integration

• Handle OpenVPN configuration file generation
• Manage server locations and endpoints
• Track connection statistics (bytes in/​out, duration)
• Monitor active VPN connections
• Implement connection limits per user

Technical Stack

Languages & Frameworks:

• Go 1.19+ (primary language)
• PostgreSQL 12+ (database)
• Native net/​http package
• database/​sql with lib/​pq driver

Key Dependencies:

• github.com/​golang-jwt/​jwt/​v5 - JWT tokens
• golang.org/​x/​crypto/​bcrypt - Password hashing
• github.com/​lib/​pq - PostgreSQL driver
• github.com/​joho/​godotenv - Environment variables

Environment Variables:

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=secure_password
DB_NAME=barqnet
JWT_SECRET=random_secret_key_min_32_chars
API_PORT=8080

File Locations

API Handlers:

• /​Users/​hassanalsahli/​Desktop/​go-hello-main/​apps/​management/​api/​auth.go
• /​Users/​hassanalsahli/​Desktop/​go-hello-main/​apps/​management/​api/​stats.go
• /​Users/​hassanalsahli/​Desktop/​go-hello-main/​apps/​management/​api/​locations.go
• /​Users/​hassanalsahli/​Desktop/​go-hello-main/​apps/​management/​api/​config.go

Shared Utilities:

• /​Users/​hassanalsahli/​Desktop/​go-hello-main/​pkg/​shared/​jwt.go
• /​Users/​hassanalsahli/​Desktop/​go-hello-main/​pkg/​shared/​otp.go
• /​Users/​hassanalsahli/​Desktop/​go-hello-main/​pkg/​shared/​database.go
• /​Users/​hassanalsahli/​Desktop/​go-hello-main/​pkg/​shared/​types.go

Database Migrations:

• /​Users/​hassanalsahli/​Desktop/​go-hello-main/​migrations/​*.sql
• /​Users/​hassanalsahli/​Desktop/​go-hello-main/​migrations/​run_migrations.go

Main Entry Point:

• /​Users/​hassanalsahli/​Desktop/​go-hello-main/​apps/​management/​main.go

Development Workflow

Adding New API Endpoint

1. Define Handler Function:

func (api *ManagementAPI) HandleNewEndpoint(w http.ResponseWriter, r *http.Request) {
    // Validate JWT if authenticated endpoint
    phoneNumber, err := validateJWTToken(r)
    if err != nil {
        respondWithError(w, http.StatusUnauthorized, "Invalid token")
        return
    }

    // Parse request body
    var req struct {
        Field1 string `json:"field1"`
        Field2 int    `json:"field2"`
    }
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        respondWithError(w, http.StatusBadRequest, "Invalid request")
        return
    }

    // Business logic
    result, err := api.processRequest(req)
    if err != nil {
        respondWithError(w, http.StatusInternalServerError, err.Error())
        return
    }

    // Success response
    respondWithJSON(w, http.StatusOK, map[string]interface{}{
        "success": true,
        "data": result,
    })
}

1. Register Route in main.go:

http.HandleFunc("/​v1/​category/​action", mgmtAPI.HandleNewEndpoint)

1. Test Endpoint:

curl -X POST http://localhost:8080/​v1/​category/​action \
  -H "Content-Type: application/​json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"field1": "value", "field2": 123}'

Adding Database Migration

1. Create Migration File:

-- migrations/​005_descriptive_name.sql

-- UP Migration
CREATE TABLE IF NOT EXISTS new_table (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_new_table_user_id ON new_table(user_id);

-- DOWN Migration (in comments)
-- DROP TABLE IF EXISTS new_table;

1. Run Migration:

# Automatic on app start
go run apps/​management/​main.go

# Or manual
go run migrations/​run_migrations.go

Code Quality Standards

Error Handling

// BAD
user, _ := getUserByPhone(phone)

// GOOD
user, err := getUserByPhone(phone)
if err != nil {
    log.Printf("[ERROR] Failed to get user: %v", err)
    return nil, fmt.Errorf("user lookup failed: %w", err)
}

Logging

log.Printf("[AUTH] User %s logged in successfully", phoneNumber)
log.Printf("[ERROR] Database connection failed: %v", err)
log.Printf("[INFO] Starting server on port %s", port)

Database Queries

// BAD (SQL injection risk)
query := fmt.Sprintf("SELECT * FROM users WHERE phone='%s'", phone)

// GOOD (parameterized)
query := "SELECT * FROM users WHERE phone_number = $1"
row := db.QueryRow(query, phone)

Testing Requirements

Unit Tests

Create *_test.go files alongside source files:

func TestGenerateJWT(t *testing.T) {
    token, err := GenerateJWT("+1234567890", 1)
    if err != nil {
        t.Fatalf("Expected no error, got %v", err)
    }
    if token == "" {
        t.Fatal("Expected token, got empty string")
    }
}

Integration Tests

Test API endpoints with real database:

func TestRegisterEndpoint(t *testing.T) {
    // Setup test database
    // Make HTTP request
    // Verify response
    // Cleanup
}

Performance Considerations

1. Database Connection Pooling:

db.SetMaxOpenConns(25)
db.SetMaxIdleConns(5)
db.SetConnMaxLifetime(5 * time.Minute)

1. Context Timeouts:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

1. Proper Indexing:

• Index all foreign keys
• Index frequently queried columns
• Use composite indexes for multi-column queries

Security Checklist

• All passwords hashed with bcrypt (cost ≥ 12)
• JWT secret stored in environment variable (≥32 chars)
• All database queries parameterized
• Rate limiting on authentication endpoints
• HTTPS enforced in production
• CORS configured for allowed origins
• Input validation on all endpoints
• Error messages don't leak sensitive info
• Tokens have appropriate expiry times
• Refresh tokens properly rotated

Common Tasks

Add New User Field

1. Add migration: ALTER TABLE users ADD COLUMN new_field TYPE;
2. Update pkg/​shared/​types.go User struct
3. Update affected API handlers
4. Update database queries

Implement New Auth Method

1. Create handler in apps/​management/​api/​auth.go
2. Add route in apps/​management/​main.go
3. Update JWT claims if needed
4. Add tests
5. Document in API_CONTRACT.md

Add Statistics Tracking

1. Design table schema in migration
2. Create handler in apps/​management/​api/​stats.go
3. Implement aggregation queries
4. Add indexes for performance
5. Create views for common queries

Documentation Requirements

For every backend change, update:

1. API_CONTRACT.md - API endpoint documentation
2. BACKEND_README.md - Architecture and setup
3. Code comments - Function documentation
4. Migration files - Clear up/​down migrations with comments

Deployment

Production Build

# Build binary
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
  -ldflags="-w -s" \
  -o bin/​vpnmanager \
  ./​apps/​management/​main.go

# Run
./​bin/​vpnmanager

Systemd Service

[Unit]
Description=BarqNet Backend
After=network.target postgresql.service

[Service]
Type=simple
User=vpnmanager
WorkingDirectory=/​opt/​barqnet
Environment="JWT_SECRET=xxx"
Environment="DB_HOST=localhost"
ExecStart=/​opt/​barqnet/​bin/​vpnmanager
Restart=always

[Install]
WantedBy=multi-user.target

When to Use This Skill

✅ Use this skill when:

• Adding or modifying backend API endpoints
• Writing database migrations
• Implementing authentication/​authorization
• Working with JWT tokens
• Integrating OpenVPN functionality
• Optimizing database queries
• Debugging backend issues
• Writing backend tests

❌ Don't use this skill for:

• Frontend/​client development (use barqnet-client skill)
• Client-backend integration (use barqnet-integration skill)
• Documentation writing (use barqnet-documentation skill)
• Code auditing (use barqnet-audit skill)

Quick Reference

Build: go build -o bin/​vpnmanager ./​apps/​management/​main.go Run: go run apps/​management/​main.go Test: go test ./​... Format: go fmt ./​... Lint: golangci-lint run Migrations: Auto-run on startup Logs: Check console output with [TAG] prefixes

Success Criteria

A backend change is complete when:

1. ✅ Code compiles without errors
2. ✅ All tests pass
3. ✅ Database migrations run successfully
4. ✅ API endpoints return correct responses
5. ✅ Error handling covers edge cases
6. ✅ Security best practices followed
7. ✅ Documentation updated
8. ✅ Logging added for debugging