rideaware-api/README.md

Here's a rewritten README for your Go version:

# RideAware API

<i>Train with Focus. Ride with Awareness</i>

RideAware API is the backend service for the RideAware platform, built with Go and PostgreSQL. It provides comprehensive endpoints for user authentication, profile management, and cycling performance tracking.

RideAware is a **comprehensive cycling training platform** designed to help riders stay aware of their performance, progress, and goals.

Whether you're building a structured training plan, analyzing ride data, or completing workouts indoors, RideAware keeps you connected to every detail of your ride.

## Tech Stack

- **Language**: Go 1.21+
- **Database**: PostgreSQL
- **ORM**: GORM
- **Router**: Chi v5
- **Auth**: JWT (Access + Refresh tokens)
- **Email**: Resend
- **Containerization**: Podman/Docker

## Getting Started

### Prerequisites

Ensure you have the following installed on your system:

- Go 1.21 or later
- PostgreSQL 12 or later
- Podman or Docker
- Git

### Setting Up the Project

1. **Clone the Repository**

   ```bash
   git clone https://github.com/VeloInnovate/rideaware-api.git
   cd rideaware-api

2. Install Dependencies

   go mod download
   go mod tidy
   

3. Configure Environment Variables

   Create a .env file in the root directory:

   # Database
   PG_USER=postgres
   PG_PASSWORD=your_password
   PG_HOST=localhost
   PG_PORT=5432
   PG_DATABASE=rideaware
   
   # Server
   PORT=5000
   
   # Security
   JWT_SECRET_KEY=your-super-secret-key-change-in-production
   
   # Email Service
   RESEND_API_KEY=re_your_resend_api_key
   SENDER_EMAIL=noreply@rideaware.app
   

4. Set Up the Database

   Ensure PostgreSQL is running and create the database:

   createdb rideaware
   

   GORM will automatically run migrations on startup.

Running Locally

Option 1: Direct Execution

go run main.go

The API will be available at http://localhost:5000

Option 2: Build and Run Binary

go build -o server .
./server

Running with Podman/Docker

Quick Start (with build script)

chmod +x build.sh
./build.sh --run

This will build the image and start a container.

Manual Build

1. Build the Image

   podman build -t rideaware:latest .
   

2. Run the Container

   podman run -d \
     --name rideaware-api \
     -p 5000:5000 \
     --env-file .env \
     rideaware:latest
   

3. View Logs

   podman logs -f rideaware-api
   

The API will be available at http://localhost:5000

API Documentation

Health Check

GET /health

Response: OK

Authentication

Sign Up

POST /api/signup
Content-Type: application/json

{
  "username": "cyclist",
  "password": "SecurePass123",
  "email": "cyclist@example.com",
  "first_name": "John",
  "last_name": "Cyclist"
}

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 900,
  "user_id": 1,
  "username": "cyclist",
  "email": "cyclist@example.com"
}

Login

POST /api/login
Content-Type: application/json

{
  "username": "cyclist",
  "password": "SecurePass123"
}

Request Password Reset

POST /api/password-reset/request
Content-Type: application/json

{
  "email": "cyclist@example.com"
}

Confirm Password Reset

POST /api/password-reset/confirm
Content-Type: application/json

{
  "token": "reset_token_from_email",
  "new_password": "NewSecurePass123"
}

Logout

POST /api/logout

Protected Routes

All protected routes require the Authorization: Bearer <access_token> header.

Get User Profile

GET /api/protected/profile
Authorization: Bearer <access_token>

Testing

Run the test suite:

chmod +x test-api.sh
./test-api.sh

This will test:

• User signup
• Login
• Protected routes
• Password reset
• Error handling

Development

Running Tests

./test-api.sh

Building a New Binary

go build -o server .

Code Formatting

go fmt ./...

Linting

go vet ./...

Deployment

Environment Variables for Production

JWT_SECRET_KEY=<generate-secure-random-key>
RESEND_API_KEY=<your-resend-production-key>
PG_PASSWORD=<strong-database-password>

Building for Production

./build.sh -t prod --no-cache --run

Or push to registry:

./build.sh -t prod -r docker.io/username --push

Troubleshooting

Database Connection Errors

Ensure PostgreSQL is running and .env variables are correct:

psql -h localhost -U postgres -d rideaware

Port Already in Use

Change the PORT in .env or stop the running container:

podman kill rideaware-api
podman rm rideaware-api

Docker Permission Issues

Run podman with sudo or add your user to the podman group:

sudo usermod -aG podman $USER

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.

Support

For issues, questions, or suggestions, please open an issue on GitHub or contact the development team.