Chirpy 🐦

A Twitter-like microblogging platform built with Go, featuring user authentication, chirp posting, and profanity filtering.

🚀 Features

• User Management: User registration and authentication with secure password hashing
• Chirp System: Post short messages (chirps) up to 140 characters
• Profanity Filtering: Automatic content moderation using a built-in profanity filter
• RESTful API: Clean HTTP API endpoints for all operations
• Database Integration: PostgreSQL database with automatic schema management
• Security: bcrypt password hashing and UUID-based identifiers
• Metrics: Built-in visit counter and admin metrics

🏗️ Architecture

• Backend: Go (Golang) with standard library HTTP server
• Database: PostgreSQL with automatic code generation via SQLC
• Authentication: bcrypt password hashing
• API: RESTful HTTP endpoints
• Schema Management: Goose migrations for database versioning

📋 Prerequisites

Before running Chirpy, ensure you have the following installed on your machine:

• Go 1.24.1 or later - Download here
• PostgreSQL 12 or later - Download here

Optional Tools (for development)

• Goose - For database migrations: go install github.com/pressly/goose/v3/cmd/goose@latest
• SQLC - For code generation: go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest

🛠️ Installation & Setup

1. Clone the Repository

git clone https://github.com/bernardodestefano/chirpy.git
cd chirpy

2. Install Dependencies

go mod download

3. Database Setup

Create PostgreSQL Database

# Connect to PostgreSQL as superuser
psql -U postgres

# Create database and user
CREATE DATABASE chirpy;
CREATE USER chirpy_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE chirpy TO chirpy_user;
\q

Run Database Migrations

# Set your database URL
export DB_URL="postgres://chirpy_user:your_secure_password@localhost:5432/chirpy?sslmode=disable"

# Run migrations (if you have Goose installed)
goose -dir sql/schema postgres "$DB_URL" up

Note: If you don't have Goose installed, you can manually run the SQL files in sql/schema/ in order:

1. 001_users.sql
2. 002_chirps.sql
3. 003_users_hashed_password.sql

4. Environment Configuration

Create a .env file in the project root:

# Database connection
DB_URL=postgres://chirpy_user:your_secure_password@localhost:5432/chirpy?sslmode=disable

# Platform environment (dev/prod)
PLATFORM=dev

5. Generate Database Code (if using SQLC)

# Generate Go code from SQL queries
sqlc generate

🚀 Running the Application

Development Mode

# Run the application
go run main.go

The server will start on http://localhost:8080

Production Build

# Build the binary
go build -o chirpy .

# Run the binary
./chirpy

📡 API Endpoints

Health Check

• GET /api/healthz - Health check endpoint

User Management

• POST /api/users - Create a new user
• POST /api/login - User authentication

Chirps

• POST /api/chirps - Create a new chirp
• GET /api/chirps - Get all chirps
• GET /api/chirps/{chirpID} - Get a specific chirp

Admin

• GET /admin/metrics - View application metrics
• POST /admin/reset - Reset metrics and delete all users (dev only)

Static Files

• GET /app/* - Serve static files (HTML, CSS, JS)

🗄️ Database Schema

Users Table

CREATE TABLE users (
    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    email TEXT UNIQUE NOT NULL,
    hashed_password TEXT NOT NULL
);

Chirps Table

CREATE TABLE chirps (
    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    body TEXT NOT NULL,
    user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE
);

🔧 Configuration

Environment Variables

Variable	Description	Default
DB_URL	PostgreSQL connection string	Required
PLATFORM	Environment (dev/prod)	dev

Database Configuration

The application uses the following PostgreSQL extensions:

• pgcrypto - For UUID generation and cryptographic functions

🧪 Testing

Run the test suite:

# Run all tests
go test ./...

# Run specific package tests
go test ./internal/auth/...

# Run tests with verbose output
go test -v ./...

📁 Project Structure

chirpy/
├── assets/                 # Static assets (logo, etc.)
├── internal/              # Internal application code
│   ├── auth/             # Authentication utilities
│   ├── database/         # Database models and queries
│   └── helpers.go        # Helper functions
├── sql/                  # Database-related files
│   ├── queries/          # SQL queries for SQLC
│   └── schema/           # Database migrations
├── main.go               # Application entry point
├── go.mod                # Go module file
├── go.sum                # Go module checksums
├── sqlc.yaml             # SQLC configuration
└── README.md             # This file

🚨 Security Features

• Password Hashing: bcrypt with default cost factor
• UUID Identifiers: Prevents enumeration attacks
• Input Validation: Comprehensive parameter validation
• Profanity Filtering: Content moderation
• CORS Protection: Built-in security headers

🔍 Troubleshooting

Common Issues

1. Database Connection Failed

   • Verify PostgreSQL is running
   • Check DB_URL environment variable
   • Ensure database and user exist

2. Migration Errors

   • Check database permissions
   • Verify SQL syntax in migration files
   • Ensure migrations are run in order

3. Port Already in Use

   • Change the port in main.go (line 298)
   • Kill existing processes using port 8080

Debug Mode

Set PLATFORM=dev in your .env file to enable:

• Reset endpoint access
• Detailed logging
• Development-only features

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📄 License

This project is open source and available under the MIT License.

🆘 Support

If you encounter any issues or have questions:

1. Check the troubleshooting section above
2. Review the API documentation
3. Open an issue on GitHub
4. Check the Go and PostgreSQL documentation

---

Happy Chirping! 🐦✨