Skip to content

egeuysall/ryva-archive

BranchesTags

Repository files navigation

Ryva

Modern SaaS platform built with Next.js 16, React 19, and Go.

Quick Start

Prerequisites

  • Node.js 25.1.0+ & pnpm 10.20.0+
  • Go 1.25.3+
  • Air (Go hot reload tool)
  • Docker & Docker Compose
  • pre-commit framework

Setup

Automated Setup (Recommended)

# Clone the repository
git clone https://github.com/egeuysall/ryva.git
cd ryva

# Run the automated setup script
make setup-dev
make setup-dev-auto

The setup script will:

  • Verify all prerequisites (Node.js, Go, pnpm, Docker, etc.)
  • Check project structure integrity
  • Create .env files from examples (auto-creates in --auto mode)
  • Install dependencies (frontend + backend)
  • Set up git hooks (pre-commit, pre-push, commit-msg)
  • Optionally run build verification tests (skipped in --auto mode)
  • Provide a summary and quick reference guide

Options:

  • --auto or -a: Run in automatic mode without prompts (useful for CI/CD)
  • --help or -h: Show help message

Manual Setup

# Install Air for Go hot reloads
go install github.com/cosmtrek/air@latest

# Install pre-commit
pip install pre-commit  # or: brew install pre-commit

# Clone and setup
git clone https://github.com/egeuysall/ryva.git
cd ryva

# Install dependencies
make install

# Set up git hooks (includes commit message validation)
make pre-commit-install

# Set up environment variables
cp .env.example .env
cp apps/web/.env.example apps/web/.env
cp apps/api/.env.example apps/api/.env
# Edit .env files with your credentials

# Start development (migrations run automatically)
make dev

Visit:

Stack

  • Frontend: Next.js 16 (App Router), React 19, Tailwind CSS v4, TypeScript
  • Backend: Go 1.25 with Chi/Gorilla router, PostgreSQL
  • Database: PostgreSQL (Supabase or self-hosted)
  • Infrastructure: Docker, Caddy reverse proxy, GitHub Actions CI/CD
  • Proxy: Caddy with rate limiting and SSL
  • Monitoring: Sentry, health checks, logging
  • Hot Reload: Air (Go) + Next.js Fast Refresh

Development

Primary Commands (Makefile)

make help            # Show all available commands
make dev             # Start both servers with hot reload
make dev-web         # Start only frontend
make dev-api         # Start only backend (with Air)
make build           # Build all applications
make test            # Run all tests
make lint            # Lint all code
make format          # Format all code
make clean           # Clean build artifacts

Frontend-Specific (apps/web)

cd apps/web
pnpm run dev         # Start Next.js dev server
pnpm run build       # Build for production
pnpm run lint        # Lint TypeScript/React
pnpm run format      # Format with Prettier
pnpm run type-check  # TypeScript type checking

Backend-Specific (apps/api)

cd apps/api
make dev             # Start with Air (hot reload)
make build           # Build binary
make test            # Run tests
make lint            # Run golangci-lint
make format          # Format with gofmt

Docker & Infrastructure

# Local development with Docker
docker compose -f docker-compose.local.yml up -d
curl http://localhost/health          # Test API via Caddy
curl http://test.localhost           # Test Caddy directly

# Production deployment
docker compose up -d                   # Uses GHCR images
docker compose ps                      # Check status
docker compose logs -f                 # View logs

# Infrastructure commands
make docker-build     # Build all images
make docker-up        # Start containers
make docker-down      # Stop containers
make docker-logs      # View logs

Project Structure

ryva/
├── apps/
│   ├── web/              # Next.js frontend
│   │   ├── src/
│   │   │   ├── app/      # App Router pages
│   │   │   ├── components/
│   │   │   ├── modules/  # Feature modules
│   │   │   └── lib/      # Utilities
│   │   └── package.json  # Frontend dependencies & scripts
│   └── api/              # Go backend
│       ├── cmd/server/   # Application entry
│       ├── internal/
│       │   ├── modules/  # Feature modules
│       │   ├── config/   # Configuration
│       │   ├── router/   # HTTP routing
│       │   └── shared/   # Shared utilities
│       ├── db/
│       │   ├── migrations/  # SQL migrations
│       │   └── queries/     # Database queries
│       └── Makefile      # Go-specific commands
├── infra/
│   ├── caddy/           # Reverse proxy with rate limiting
│   │   ├── Dockerfile   # Custom Caddy build
│   │   ├── Caddyfile   # Production config
│   │   └── Caddyfile.local # Development config
│   └── sentry/          # Error tracking setup
├── docs/                # Documentation
│   ├── infrastructure/  # Infrastructure docs
│   ├── development/     # Development guides
│   └── frontend/        # Frontend docs
├── scripts/             # Utility scripts
├── Makefile             # Root orchestration (primary interface)
├── docker-compose.yml   # Production container orchestration
└── docker-compose.local.yml # Local development

Key Features

  • Makefile-based build system - Cross-language orchestration
  • Hot reload - Both frontend (Next.js) and backend (Air)
  • Automatic migrations - Run on API startup
  • Pre-commit hooks - Code quality + Conventional Commits enforcement
  • Type-safe - Strict TypeScript, explicit Go types
  • Modular architecture - Clean separation of concerns
  • Docker ready - Multi-stage builds with health checks
  • Production Infrastructure - Caddy proxy with edge-level rate limiting, SSL
  • CI/CD - Automated deployments with canary + rolling updates
  • State Management - TanStack Query + Zustand
  • Comprehensive Testing - Vitest, Playwright, Go testing with 80% coverage

Architecture Principles

Frontend (Next.js + React)

  • Server Components by default
  • Client Components ('use client') only for: events, state, browser APIs, hooks
  • Strict TypeScript, no any types
  • Mobile-first responsive design with dark mode
  • Type all component props with interfaces

Backend (Go)

  • Clean architecture: handler → service → repository
  • Never ignore errors, always return and wrap them
  • Use context.Context for all database operations
  • Keep handlers thin, business logic in services
  • Validate all inputs before processing

State Management

  • TanStack Query - Server state, caching, data synchronization
  • Zustand - Client state, UI state, user preferences
  • Type-safe stores and hooks
  • DevTools integration for debugging

Testing

Comprehensive testing infrastructure with 80% coverage enforcement in CI.

Quick Commands

# Run all tests (frontend + backend)
make test

# Frontend tests
cd apps/web
pnpm test              # Unit & integration tests
pnpm test:watch        # Watch mode
pnpm test:ui           # UI mode
pnpm test:coverage     # With coverage
pnpm test:e2e          # E2E tests (Playwright)

# Backend tests
cd apps/api
make test              # All tests
make test-unit         # Unit tests only
make test-integration  # Integration tests only
make test-e2e          # E2E tests only
make test-coverage     # With coverage report

Testing Stack

  • Frontend: Vitest + React Testing Library + Playwright
  • Backend: Go testing + testify + httptest
  • CI/CD: GitHub Actions with parallel execution and coverage enforcement (80%)
  • Coverage: Automated threshold checking and reporting

CI/CD Pipeline

Production-grade continuous integration and deployment with GitHub Actions.

Automated Checks

Every PR and push triggers:

API (Go):

  • Linting (golangci-lint v2.3.0)
  • Unit & integration tests
  • 80% coverage enforcement
  • Security scanning (Gosec + govulncheck)
  • Binary build verification

Web (Next.js):

  • ESLint & Prettier checks
  • TypeScript type checking
  • Unit tests with 80% coverage
  • E2E tests (Playwright)
  • Production build verification
  • Security audits (pnpm audit)

Commit Validation:

  • Conventional Commits enforcement
  • PR title validation

Branch Protection

  • master: Production-ready code only (requires PR + 1 approval + all checks)
  • develop: Integration branch (requires PR + 1 approval + all checks)
  • All commits must follow Conventional Commits

Development Workflow

We use Git Flow with Conventional Commits.

Branch Naming

Format: <type>/<ticket-number>-<short-description>

Types: feature/, fix/, hotfix/, release/, refactor/, docs/, test/, chore/

Examples:

feature/RYVA-123-user-authentication
fix/RYVA-456-login-validation
hotfix/RYVA-789-security-patch

Commit Messages

Format: <type>(<scope>): <subject>

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Examples:

feat(auth): add JWT token validation
fix(api): resolve race condition in user service
docs(readme): update installation steps

Note: Commit messages are automatically validated by pre-commit hooks. Invalid messages (e.g., "Debug project") will be rejected. The commit-msg hook ensures all commits follow Conventional Commits format.

Daily Workflow

# 1. Update develop
git checkout develop
git pull origin develop

# 2. Create feature branch
git checkout -b feature/RYVA-123-my-feature

# 3. Make changes and test
# ... code changes ...
make test && make lint

# 4. Commit with conventional format
git add .
git commit -m "feat(api): add user endpoint"

# 5. Push and create PR
git push origin feature/RYVA-123-my-feature
# Create PR on GitHub targeting develop

Pull Request Requirements

Before merge:

  • At least 1 approval from code owner
  • All CI/CD checks pass (lint, test, build, security)
  • 80% test coverage maintained
  • No merge conflicts
  • All conversations resolved
  • Commit messages follow convention

Release Process

We follow Semantic Versioning: MAJOR.MINOR.PATCH

  • MAJOR: Breaking changes
  • MINOR: New features (backwards compatible)
  • PATCH: Bug fixes (backwards compatible)

Creating a Release

# 1. Create release branch from develop
git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

# 2. Update version numbers
# - Update package.json versions
# - Update API version constants
# - Update CHANGELOG.md

# 3. Final testing
cd apps/api && make test-all
cd apps/web && pnpm test && pnpm test:e2e

# 4. Commit version bump
git add .
git commit -m "chore(release): bump version to 1.2.0"

# 5. Push and create PR to master
git push origin release/v1.2.0
# Create PR with title: "Release v1.2.0"
# Requires 2 approvals for release branches

# 6. After merge, tag the release
git checkout master
git pull origin master
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

# 7. Merge back to develop
git checkout develop
git merge master
git push origin develop

# 8. Cleanup
git branch -d release/v1.2.0
git push origin --delete release/v1.2.0

Release Checklist

  • All features merged to develop
  • All tests passing with 80%+ coverage
  • Documentation updated
  • CHANGELOG.md updated
  • Version numbers bumped
  • Release notes prepared
  • Database migrations tested
  • Environment variables documented
  • Deployment plan ready
  • Rollback plan documented

Hotfix Process

For urgent production fixes:

# 1. Create hotfix branch from master
git checkout master
git pull origin master
git checkout -b hotfix/RYVA-999-critical-fix

# 2. Make the fix and test thoroughly
# ... fix the issue ...
make test-all

# 3. Commit and push
git add .
git commit -m "fix(api): patch critical security vulnerability"
git push origin hotfix/RYVA-999-critical-fix

# 4. Create PR to master (fast-track review)
# 5. After merge, tag with patch version
git checkout master
git pull
git tag -a v1.2.1 -m "Hotfix version 1.2.1"
git push origin v1.2.1

# 6. Merge back to develop
git checkout develop
git merge master
git push origin develop

Hotfix Criteria:

  • 🔥 Security vulnerabilities
  • 🐛 Critical bugs affecting all users
  • 💥 Production outages
  • 📉 Data integrity issues

Database Migrations

Migrations run automatically when the API starts.

Create New Migration

make db-create-migration name=add_users_table

This creates timestamped .up.sql and .down.sql files in apps/api/db/migrations/.

Docker

# Local development
docker compose -f docker-compose.local.yml up -d
docker compose -f docker-compose.local.yml logs -f

# Production
docker compose up -d
docker compose ps

# Make commands
make docker-build     # Build images
make docker-up        # Start containers
make docker-down      # Stop containers
make docker-logs      # View logs

Documentation

Contributing

We welcome contributions! Please read our Contributing Guide for:

  • Branch naming conventions
  • Commit message standards
  • Pull request process
  • Code style guidelines
  • Development workflow

Quick tips:

  1. Always branch from develop
  2. Use conventional commit messages
  3. Ensure 80% test coverage
  4. Run tests and linters before pushing
  5. Create descriptive PRs with the template

License

See LICENSE

Built with ❤️ using Next.js, React, and Go

About

All your projects in one intelligent workspace.

ryva.dev

Topics

golang tool nextjs developer

Resources

Readme

License

View license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 8

Production Release prod-20260115-024945-ac9d02c3953e372790c646da140f4bdb2d15bdb7 Latest
Jan 15, 2026
+ 7 releases

Packages

 
 
 

Contributors

Languages