{"id":43149273,"url":"https://github.com/jwallace145/crux-project","last_synced_at":"2026-01-31T23:54:25.500Z","repository":{"id":319624890,"uuid":"1078050813","full_name":"jwallace145/crux-project","owner":"jwallace145","description":"Empowering rock climbers to discover new routes, log indoor/outdoor sessions, and engage with the community","archived":false,"fork":false,"pushed_at":"2025-11-03T06:39:15.000Z","size":226,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-03T08:15:04.178Z","etag":null,"topics":["aws","docker","fiber","go","postgresql","terraform"],"latest_commit_sha":null,"homepage":"https://cruxproject.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jwallace145.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-17T06:16:28.000Z","updated_at":"2025-11-03T06:39:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"4c669e44-5289-410a-b1aa-19aaa781d6c7","html_url":"https://github.com/jwallace145/crux-project","commit_stats":null,"previous_names":["jwallace145/crux-backend","jwallace145/crux-project"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/jwallace145/crux-project","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwallace145%2Fcrux-project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwallace145%2Fcrux-project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwallace145%2Fcrux-project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwallace145%2Fcrux-project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jwallace145","download_url":"https://codeload.github.com/jwallace145/crux-project/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwallace145%2Fcrux-project/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28961128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T23:03:11.038Z","status":"ssl_error","status_checked_at":"2026-01-31T22:56:44.691Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","docker","fiber","go","postgresql","terraform"],"created_at":"2026-01-31T23:54:24.854Z","updated_at":"2026-01-31T23:54:25.493Z","avatar_url":"https://github.com/jwallace145.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CruxBackend\n\n[![Release and Deploy](https://github.com/jwallace145/crux-project/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/jwallace145/crux-project/actions/workflows/release.yml)\n\nA high-performance rock climbing API built with Go and [Fiber](https://gofiber.io/) that powers web and mobile applications for the climbing community.\n\n## Overview\n\nCruxBackend is the central backend service for climbers to discover routes, log climbs, track progress, and connect with the climbing community. Built for scalability and deployed on AWS with containerized microservices.\n\n## Core MVP Features\n\nThese are the essential features that define the product. Use this list to guide development priorities:\n\n### 1. Natural Language Route Search\n**Goal:** Enable climbers to find routes using conversational queries\n**Example:** _\"Give me all single pitch 5.8-5.9 trad routes within a 2 hour drive of Denver, CO\"_\n**Status:** 🚧 Not Started\n\n**Key Requirements:**\n- Parse natural language queries (difficulty, style, location, distance)\n- Geocoding and distance calculations\n- Filter by route attributes (pitch count, grade, type)\n- Return ranked results\n\n### 2. Climb Logging \u0026 Progress Tracking\n**Goal:** Record climbs (outdoor \u0026 indoor) and track progress over time\n**Features:**\n- Log outdoor climbs with route association\n- Log indoor gym sessions\n- Track climbing partners\n- View personal climbing history and statistics\n- Filter climbs by date range\n\n**Status:** ✅ Core logging implemented, analytics pending\n\n### 3. Community \u0026 Social Features\n**Goal:** Enable climbers to share experiences and find partners\n**Features:**\n- Comment on specific routes\n- Comment on other climbers' logged climbs (if following)\n- Follow/unfollow climbers\n- Find climbing partners based on shared interests\n- Route ratings and reviews\n\n**Status:** 🚧 Not Started\n\n\n## Architecture\n\n### Local Development\n```\n┌─────────────────┐\n│  Developer      │\n└────────┬────────┘\n         │\n    ┌────▼─────────┐\n    │   Fiber API  │ (Docker Container)\n    │   Port 3000  │\n    └────┬─────────┘\n         │\n    ┌────▼──────────┐\n    │  PostgreSQL   │ (Docker Container)\n    │   Port 5432   │\n    └───────────────┘\n```\n\n### Production (AWS)\n```\nInternet\n    │\n    ▼\n┌─────────────────────────┐\n│   Route53 DNS           │\n│   *-api.domain.com      │\n└──────────┬──────────────┘\n           │\n    ┌──────▼──────────┐\n    │  Application    │\n    │  Load Balancer  │\n    │  (ALB)          │\n    └──────┬──────────┘\n           │\n    ┌──────▼────────────┐\n    │  ECS Fargate      │\n    │  - Go Fiber API   │\n    │  - Auto-scaling   │\n    │  - Health checks  │\n    └──────┬────────────┘\n           │\n    ┌──────▼────────────┐\n    │  RDS PostgreSQL   │\n    │  (Private subnet) │\n    └───────────────────┘\n\n┌─────────────────────────┐\n│  EC2 Bastion Host       │\n│  (Network debugging)    │\n└─────────────────────────┘\n```\n\n## Quick Start\n\n### Prerequisites\n- [Go 1.24+](https://go.dev/dl/)\n- [Docker](https://docs.docker.com/get-docker/) \u0026 [Docker Compose](https://docs.docker.com/compose/install/)\n- [Make](https://www.gnu.org/software/make/)\n\n### Local Development\n\n```bash\n# Start all services (API + Database)\nmake up\n\n# Or run API locally with auto-reload (starts DB container)\nmake run\n\n# View logs\nmake logs          # All services\nmake logs-api      # API only\nmake logs-db       # Database only\n\n# Run tests with coverage\nmake test\n\n# Format code\nmake fmt\n\n# Lint code\nmake lint\n\n# Run all pre-commit checks\nmake pre-commit\n\n# Database management\nmake db-shell      # Open PostgreSQL shell\nmake bootstrap     # Run migrations\nmake reset         # Reset db (prompts for confirmation)\n\n# View all available commands\nmake help\n```\n\nThe API will be available at `http://localhost:3000`\n\n### Health Check\n```bash\ncurl http://localhost:3000/health\n```\n\n### API Endpoints\n\n#### Authentication\n- `POST /login` - User login (returns JWT tokens)\n- `POST /logout` - User logout (revokes session)\n- `POST /refresh` - Refresh access token\n\n#### Users\n- `POST /users` - Create new user account\n\n#### Climbs\n- `POST /climbs` - Log a climb (outdoor or indoor)\n- `GET /climbs?user_id=X\u0026start_date=Y\u0026end_date=Z` - Get user's climbs\n\n## API Documentation\n\n### Interactive API Documentation with Scalar\n\nCruxBackend provides comprehensive, interactive API documentation powered by [Scalar](https://guides.scalar.com/scalar/introduction), designed for developers who want to explore, test, and integrate with the API.\n\n**Live Documentation:** [https://jwallace145.github.io/crux-backend](https://jwallace145.github.io/crux-backend)\n\n#### Features\n\nThe interactive documentation provides:\n- **Live API Testing** - Test all endpoints directly from your browser\n- **Multiple Environments** - Switch between local development (localhost:3000) and deployed servers (dev-api.cruxproject.io)\n- **Request/Response Examples** - View example requests and responses for every endpoint\n- **Schema Documentation** - Detailed documentation of all data models and validation rules\n- **Authentication Flow** - Test the complete authentication workflow with JWT tokens\n- **Search \u0026 Browse** - Quickly find endpoints organized by category (Health, Auth, Users, Climbs)\n- **OpenAPI Specification** - Based on OpenAPI 3.0.3 standard for easy integration with other tools\n\n#### Local Development\n\nWhen running the API locally, the documentation is available at:\n```\nhttp://localhost:3000/docs\n```\n\nThe OpenAPI specification file can be accessed at:\n```\nhttp://localhost:3000/docs/openapi.yaml\n```\n\n#### Using the Documentation\n\n1. **Select Environment** - Use the server dropdown to choose between local development or deployed servers\n2. **Browse Endpoints** - Navigate through all available API endpoints organized by tags\n3. **Try It Out** - Click \"Try It\" on any endpoint to send real requests to the selected environment\n4. **Authentication** - Login via `POST /login` to test authenticated endpoints (cookies are handled automatically)\n5. **View Schemas** - Explore detailed request and response schemas with validation rules\n\n**Environment Switching:**\nThe documentation supports testing against multiple environments without leaving the page. Simply select your target environment from the server dropdown:\n- **Local Development** (`http://localhost:3000`) - Test changes during local development\n- **Development Server** (`http://dev-api.cruxproject.io`) - Test deployed changes in the dev environment\n\n#### For Developers\n\nThe OpenAPI specification can be used with various tools:\n- Import into Postman, Insomnia, or other API clients\n- Generate client SDKs using [OpenAPI Generator](https://openapi-generator.tech/)\n- Integrate with CI/CD pipelines for API contract testing\n\nFor more information about Scalar and its features, visit the [Scalar documentation](https://guides.scalar.com/scalar/introduction).\n\n## Database Schema\n\n### Core Entities\n- **User** - Climber profiles with authentication\n  - Username, email, password hash\n  - Created/updated timestamps\n\n- **Session** - User sessions for authentication\n  - Session ID, user ID, expiration\n  - Revocation status\n\n- **Crag** - Outdoor climbing areas\n  - Name, location, description\n\n- **Wall** - Climbing walls within crags\n  - Associated with Crag (many-to-one)\n\n- **Route** - Individual climbing routes\n  - Associated with Wall (many-to-one)\n  - Grade, type, GPS coordinates, ratings\n\n- **Gym** - Indoor climbing gyms\n  - Name, location, facilities (bouldering, top rope, lead, etc.)\n  - Contact info, pricing, hours\n\n- **Climb** - Individual climb logs\n  - User, Route (outdoor) or Gym (indoor)\n  - Climb type (indoor/outdoor)\n  - Grade, date, completed status\n  - Attempts, falls, rating, notes\n\n### Migrations\nDatabase migrations are handled automatically by GORM on startup. Models are defined in the `models/` directory and registered in `internal/db/postgres.go`.\n\n## Development Workflow\n\n### Adding New Features\n\n1. **Define the feature** - Check Core MVP Features list\n2. **Create database models** - Add to `models/` and register in `internal/db/postgres.go`\n3. **Create DTOs** - Request/response models in `models/*_dto.go`\n4. **Implement handlers** - Business logic in `internal/services/\u003cdomain\u003e/`\n5. **Register routes** - Wire up in `internal/routes/`\n6. **Test locally** - `make run` and test with curl/Postman\n7. **Run checks** - `make pre-commit`\n8. **Commit** - Follow conventional commit format\n\n### Code Style\n- Format code before committing: `make fmt`\n- Imports are automatically sorted with local package prefix\n- Use structured logging with Zap (not `fmt.Println`)\n- Follow Go idioms and best practices\n\n## Infrastructure\n\n### Terraform Modules\n\nLocated in `infra/terraform/modules/`:\n\n- **vpc-network** - VPC, subnets, internet gateway, NAT gateway\n- **rds-postgresql-db** - RDS PostgreSQL database instance\n- **ecr-repository** - Docker image registry\n- **alb-ecs** - Application Load Balancer with target groups and security groups\n- **ecs-service** - ECS Fargate cluster, service, and task definitions\n- **lambda-update-task-ip** - Lambda to associate Elastic IP with ECS tasks\n- **elastic-ip** - Static IP allocation\n- **ec2-bastion-host** - Bastion host for VPC debugging\n\n### Deployment Commands\n\n```bash\n# Format Terraform code\nmake tf-fmt\n\n# Plan infrastructure changes\nmake tf-plan\n\n# Apply infrastructure changes\nmake tf-apply\n\n# Build and push Docker image to ECR\nmake ecr-deploy\n\n# Deploy to ECS (force new deployment)\nmake ecs-deploy\n\n# Complete deployment pipeline (ECR + ECS)\nmake deploy\n\n# Check ECS service status\nmake ecs-status\n\n# View ECS logs\nmake ecs-logs\n```\n\n### Environment Variables\n\n**Local Development (.env file):**\n```\nPORT=3000\nDB_HOST=localhost\nDB_PORT=5432\nDB_USER=cruxadmin\nDB_PASSWORD=cruxdbpassword\nDB_NAME=cruxdb\nDB_SSLMODE=disable\nJWT_SECRET=your-secret-key-here\n```\n\n**Production (ECS Task Definition):**\n- Configured via Terraform in `infra/terraform/api.tf`\n- Database credentials managed separately (consider AWS Secrets Manager)\n\n## Testing\n\n```bash\n# Run all tests with coverage\nmake test\n\n# Run specific test\ngo test -v ./internal/services/users/...\n\n# Run with race detection\ngo test -race ./...\n```\n\n## Roadmap\n\n### Completed ✅\n- [x] Local development environment\n- [x] Core API structure with Fiber\n- [x] PostgreSQL database with GORM\n- [x] User authentication (JWT + bcrypt)\n- [x] Session management with refresh tokens\n- [x] Climb logging API (indoor/outdoor)\n- [x] Gym model and integration\n- [x] AWS infrastructure with Terraform\n- [x] ECS Fargate deployment\n- [x] Application Load Balancer\n- [x] RDS PostgreSQL\n- [x] Docker containerization\n- [x] Interactive API documentation (OpenAPI + Scalar)\n\n### In Progress 🚧\n- [ ] Natural language route search\n- [ ] Community features (comments, following, partner matching)\n- [ ] Performance analytics and climb statistics\n- [ ] Route recommendations\n\n### Planned 📋\n- [ ] Mobile app integration\n- [ ] Real-time notifications\n- [ ] Photo uploads for climbs and routes\n- [ ] Weather integration for route conditions\n- [ ] CI/CD pipeline (GitHub Actions)\n- [ ] GraphQL endpoint (optional)\n\n## Contributing\n\n1. Install pre-commit hooks: `pre-commit install`\n2. Create a feature branch: `git checkout -b feature/your-feature`\n3. Make changes and test: `make test`\n4. Format and lint: `make pre-commit`\n5. Commit with conventional format: `git commit -m \"feat: add route search\"`\n6. Submit a pull request\n\n### Commit Message Format\n```\n\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e\n\nTypes: feat, fix, docs, style, refactor, test, chore\nExample: feat(search): add natural language route search\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Port 3000 already in use:**\n```bash\n# Find process using port\nlsof -i :3000\n# Kill process\nkill -9 \u003cPID\u003e\n```\n\n**Database connection errors:**\n```bash\n# Check if db is running\nmake status\n# View db logs\nmake logs-db\n# Reset db\nmake reset\n```\n\n**Cannot connect to Docker:**\n```bash\n# Ensure Docker is running\ndocker ps\n# Restart Docker Desktop\n```\n\n## Project Structure\n\n```\ncrux-backend/\n├── main.go                 # Application entry point\n├── models/                 # Database models and DTOs\n│   ├── user.go            # User model\n│   ├── user_dto.go        # User DTOs\n│   ├── auth_dto.go        # Auth DTOs\n│   ├── climb.go           # Climb model\n│   ├── climb_dto.go       # Climb DTOs\n│   ├── gym.go             # Gym model\n│   ├── route.go           # Route model\n│   ├── wall.go            # Wall model\n│   └── crag.go            # Crag model\n├── internal/\n│   ├── db/                # Database connection \u0026 migrations\n│   ├── routes/            # HTTP route definitions\n│   ├── services/          # Business logic handlers\n│   │   ├── auth/         # Authentication\n│   │   ├── users/        # User management\n│   │   ├── climbs/       # Climb logging\n│   │   └── docs/         # API documentation\n│   ├── utils/            # Shared utilities\n│   │   ├── logger.go     # Zap logger\n│   │   ├── jwt.go        # JWT utilities\n│   │   └── response.go   # API response helpers\n│   └── aws/              # AWS service clients\n├── docs/                 # API Documentation\n│   ├── openapi.yaml      # OpenAPI 3.0.3 specification\n│   └── README.md         # Documentation guide\n├── infra/                # Infrastructure as Code\n│   ├── terraform/        # Terraform modules\n│   │   ├── modules/     # Reusable modules\n│   │   ├── api.tf       # API infrastructure\n│   │   ├── db.tf        # Database infrastructure\n│   │   └── network.tf   # Network infrastructure\n│   └── scripts/         # Deployment scripts\n├── docker-compose.yml   # Local development stack\n├── Dockerfile.dev       # Production Docker image\n├── Dockerfile.local     # Development Docker image\n├── Makefile            # Development commands\n├── go.mod              # Go dependencies\n└── .air.toml           # Live reload config\n```\n\n## License\n\n[Add your license here]\n\n---\n\n**Status:** 🚧 Active Development\n**Current Focus:** Natural language route search MVP\n\nFor questions or issues, please open a GitHub issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwallace145%2Fcrux-project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjwallace145%2Fcrux-project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwallace145%2Fcrux-project/lists"}