Getting Started with Ocmonica¶

Last Updated: 2025-11-23

This guide helps you get ocmonica up and running quickly, whether you're developing locally or deploying to production.

Table of Contents¶

Prerequisites
Quick Start
Development Workflow
Client Usage
Next Steps

Prerequisites¶

Required Tools¶

Go 1.25.2+ - Backend development
Node.js 20+ - Frontend development
Task - Task automation (taskfile.dev)
Buf - Protobuf linting and code generation (buf.build)

Optional Tools¶

Docker - For observability stack (Jaeger, Prometheus, Grafana)
sqlite3 CLI - For database inspection
grpcurl - For testing gRPC endpoints
jq - For JSON processing

IDE Recommendations¶

VS Code with Go extension
GoLand (JetBrains)

Configure your IDE for: - Auto-format on save - golangci-lint integration - Go imports organization

Quick Start¶

1. Clone the Repository¶

git clone https://github.com/j-pye/ocmonica.git
cd ocmonica

2. Install Dependencies¶

Backend:

go mod download

Frontend:

cd web
npm install
cd ..

3. Install Development Tools¶

# Install Task (if not already installed)
# macOS
brew install go-task

# Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

# Install Buf
# macOS
brew install bufbuild/buf/buf

# Linux
curl -sSL https://github.com/bufbuild/buf/releases/download/v1.47.2/buf-Linux-x86_64 \
  -o /usr/local/bin/buf && chmod +x /usr/local/bin/buf

# Install golangci-lint
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | \
  sh -s -- -b $(go env GOPATH)/bin v1.62.2

4. Start Development Server¶

Backend Only:

task dev

Backend + Frontend (Recommended):

task dev:full

With Hot Reload:

# Backend hot reload with Air
task dev:watch

# Backend + Frontend hot reload
task dev:watch:full

Full Stack with Observability (Docker required):

# Start Jaeger, Prometheus, Grafana
docker-compose -f docker-compose.dev.yml up -d

# Start backend and frontend
task dev:full

5. Verify Installation¶

Open your browser to: - Backend API: http://localhost:8080 - Frontend: http://localhost:3000 (if running full stack) - Health Check: http://localhost:8080/health - Metrics: http://localhost:8080/metrics - Jaeger UI: http://localhost:16686 (if using Docker) - Prometheus: http://localhost:9091 (if using Docker) - Grafana: http://localhost:3001 (if using Docker)

Development Workflow¶

Hot Reload¶

Air watches Go files and rebuilds automatically:

task dev:watch

How it works: - Watches .go files in cmd/, internal/, pkg/ - Rebuilds on changes with 1-second debounce - Outputs to tmp/main (gitignored) - Configuration: .air.toml - Typical rebuild time: 2-3 seconds

Next.js has built-in hot reload:

cd web
npm run dev

How it works: - Built into Next.js dev server with Turbopack - Watches all files in web/src/ - Hot Module Replacement (< 1 second) - No configuration needed locally

Testing¶

Run All Tests:

task test

Run with Coverage:

task test:coverage
# Opens HTML report in browser

Run Specific Tests:

go test ./internal/service/...
go test ./internal/repository/sqlite/...

Code Quality¶

Format Code:

task fmt

Run Linter:

task lint

Fix Linting Issues (where possible):

task lint:fix

Security Scan:

task security:scan

Protobuf Code Generation¶

Generate Go + TypeScript Code:

task proto:gen

Lint Protobuf Files:

task proto:lint

Git Hooks¶

Install Hooks:

task hooks:install

Run Hooks Manually:

task hooks:run

What runs on commit: - Go: goimports, go fmt, golangci-lint --fast - TypeScript: npm run lint - Protobuf: buf lint, buf format - Commit message: Conventional commits validation

Hooks run in parallel and only on staged files for speed (typically < 5 sec).

Client Usage¶

REST API¶

Register a New User:

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "email": "john@example.com",
    "password": "securepassword123",
    "organization_name": "My Company"
  }'

Login:

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "password": "securepassword123"
  }'

Upload File:

curl -X POST http://localhost:8080/api/v1/files \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@document.pdf"

List Files:

curl -H "Authorization: Bearer <access_token>" \
  http://localhost:8080/api/v1/files

gRPC API¶

TypeScript/React Example:

import { createConnectTransport } from '@connectrpc/connect-web';
import { createPromiseClient } from '@connectrpc/connect';
import { FileService } from '@/gen/ocmonica/v1/file_service_connect';

// Setup transport
const transport = createConnectTransport({
  baseUrl: 'http://localhost:8080',
  useBinaryFormat: false,
});

const client = createPromiseClient(FileService, transport);

// Upload file
const response = await client.uploadFile({
  filename: 'document.pdf',
  content: fileBuffer,
  directoryId: 'dir-123',
});

Using grpcurl¶

List Services:

grpcurl -plaintext localhost:8080 list

List Methods:

grpcurl -plaintext localhost:8080 list ocmonica.v1.FileService

Call Method:

grpcurl -plaintext \
  -H "Authorization: Bearer <token>" \
  -d '{"directory_id": "root"}' \
  localhost:8080 ocmonica.v1.FileService/ListFiles

Default Credentials¶

Bootstrap Admin Account:

Username: admin
Password: admin123
Organization: default

⚠️ IMPORTANT: Change these credentials immediately after first login!

Change Password:

curl -X PUT http://localhost:8080/api/v1/auth/password \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "admin123",
    "new_password": "new_secure_password"
  }'

Troubleshooting¶

Server Won't Start¶

Port Already in Use:

# Check what's using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

Database Locked:

# Remove database file and restart
rm data/ocmonica.db
task dev

Hot Reload Not Working¶

Air Not Rebuilding: - Check .air.toml exists - Verify file is in watched directory - Check Air logs for errors

Next.js Not Reloading: - Restart dev server: npm run dev - Clear .next cache: rm -rf .next

Test Failures¶

Run Specific Test:

go test -v ./internal/service -run TestFileService_Upload

Run with Race Detector:

go test -race ./...

Protobuf Generation Issues¶

Clean Generated Code:

rm -rf gen/
task proto:gen

Update Buf Dependencies:

buf mod update

Next Steps¶

Once you have ocmonica running:

Explore the APIs:
REST API Documentation
gRPC API Documentation
Learn the Architecture:
Architecture Overview
See CLAUDE.md (Architecture section) in project root for layered architecture patterns
Authentication & Security:
Authentication Guide
See SECURITY.md in project root for security documentation
Development Guides:
Testing Guide
Code Generation Guide
See CLAUDE.md (Development Patterns section) in project root
Deployment:
See DEPLOYMENT.md in project root for deployment guide and configuration

Common Commands Reference¶

# Development
task dev                    # Start backend
task dev:full              # Start backend + frontend
task dev:watch             # Start with hot reload (backend)
task dev:watch:full        # Start with hot reload (both)

# Testing
task test                  # Run all tests
task test:coverage         # Run with coverage report
task test:integration      # Run integration tests

# Code Quality
task fmt                   # Format code
task lint                  # Run linter
task lint:fix              # Fix linting issues
task security:scan         # Security scan

# Protobuf
task proto:gen             # Generate code
task proto:lint            # Lint protobuf files

# Git Hooks
task hooks:install         # Install git hooks
task hooks:run             # Run hooks manually

# Database
task db:init               # Initialize database
task db:test               # Run database tests

# Docker
task docker:build          # Build Docker image
task docker:run            # Run in Docker
task docker:dev            # Full stack with observability

# CI/CD
task ci                    # Run all CI checks
task quality:report        # Generate quality report

Getting Help¶

Documentation: See docs/ for comprehensive guides
GitHub Issues: https://github.com/j-pye/ocmonica/issues
Discussions: https://github.com/j-pye/ocmonica/discussions
Claude Development Guide: See CLAUDE.md in project root

Happy coding! 🚀