https://github.com/pulgamecanica/matcha
Matcha - 42
https://github.com/pulgamecanica/matcha
api ruby sinatra sinatra-applications
Last synced: about 1 year ago
JSON representation
Matcha - 42
- Host: GitHub
- URL: https://github.com/pulgamecanica/matcha
- Owner: pulgamecanica
- Created: 2025-04-07T12:18:02.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-15T08:14:58.000Z (about 1 year ago)
- Last Synced: 2025-04-15T08:34:49.654Z (about 1 year ago)
- Topics: api, ruby, sinatra, sinatra-applications
- Language: Ruby
- Homepage:
- Size: 221 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🧪 Matcha API — Love & Ruby 💘
[](http://sinatrarb.com/)
[](https://www.postgresql.org/)
[](https://www.docker.com/)
[](https://rspec.info/)
[]()
[]()
> The only thing better than a Matcha latte is a **match made in Ruby**.
> This is a fully-documented, TDD-driven Sinatra API for the Matcha dating platform. It’s modular, dockerized, and optimized for love at first request 💘
---
## 📦 Tech Stack
| Layer | Tech |
|---------------|-------------------------|
| Framework | Sinatra (modular style) |
| Language | Ruby 3.2 |
| Database | PostgreSQL 14 |
| Persistence | Raw SQL + SQLHelper |
| Auth | JWT (handrolled) |
| Container | Docker + Compose |
| Testing | RSpec + Rack::Test |
| Docs | `api_doc` DSL (custom) |
| Console | IRB via bin/console |
| Tasks | Rake + Makefile |
---
## ⚙️ Features
- 🔐 **Authentication**: Email/password & social (Google, Facebook, Snapchat)
- 🧪 **TDD-first** with RSpec specs for everything
- 🧼 **Clean architecture**: Helpers, controllers, and models separated
- 🔒 **JWT-based sessions** (no gem dependencies)
- 🧠 **Robust validation** with reusable DSL-based `Validator`
- 🌍 **RESTful routes**: `/auth`, `/me`, `/users/:username`, etc.
- 🚫 **Ban & Confirm logic**: No banned or unconfirmed user can access the API
- 💾 **Smart SQL helper**: `SQLHelper.create`, `update`, `find_by`, etc.
- 🧾 **API docs**: Exportable via `make docs`
- 🐳 **Fully dockerized**
- 💬 Friendly, readable logs
---
## 🗂️ Project Structure
```
.
├── app/
│ ├── controllers/ # Modular Sinatra apps (AuthController, UsersController)
│ ├── helpers/ # Validators, SQLHelper, Request parsing, Auth, Database
│ ├── models/ # Models (User, ...)
│ ├── lib/ # Shared error classes, doc
├── config/
│ └── database.yml # Database settings
│ └── environment.rb # Loads everything
├── db/
│ ├── migrate/ # DB migrations
│ └── seeds.rb # (optional)
├── spec/ # RSpec suite
├── docker/ # Dockerfile
├── docker-compose.yml
├── Rakefile
├── Makefile
├── .env
├── config.ru
└── README.md
```
---
## 🚀 Getting Started
---
### 📘 Postman Collection
> Visit the [Postman Colleciton](https://pulgamecanica.postman.co/workspace/pulgamecanica~fddcef76-1724-4c9d-8f90-c24cfe79c2b9/collection/13231501-422c8247-c0ee-4bec-834b-ede0215c4e05?action=share&creator=13231501) to run all the API endpoints.
---
### 🔧 Local Dev (Dockerized)
```bash
git clone https://github.com/pulgamecanica/matcha
cd matcha
# Build containers
docker compose build
# Start the app
docker compose up
# Open dev console
make console
# Run the test suite
make test
```
---
## 🧪 Testing
RSpec tests live in `spec/`, with:
- Integration tests for endpoints
- Unit tests for helpers
- Full TDD on auth, validation, sessions, and core models
```bash
make test
```
---
## 🛠️ Developer Shortcuts (Makefile)
```bash
make create # db:create
make migrate # db:migrate
make test # run all specs
make console # open IRB console
make docs # export route documentation
```
---
## 🔐 Authentication
Stateless JWT (no libraries!) via `SessionToken`.
```rb
SessionToken.generate(user_id) # => "encoded.jwt.token"
SessionToken.decode(token) # => { "user_id" => 42, ... }
```
---
## 📘 API Documentation
Each route is documented inline with the `api_doc` DSL.
To export to markdown:
```bash
make docs
```
➡ Output: `docs/exported.md`
Example:
```ruby
api_doc "/auth/register", method: :post do
description "Register a new user"
param :email, String, required: true
param :username, String, required: true
param :password, String, required: true
response 201, "User created"
end
```
---
## 🚀 Endpoints (Implemented)
- `POST /auth/register`
- `POST /auth/login`
- `POST /auth/social`
- `GET /me`
- `PATCH /me`
- `DELETE /me`
- `GET /users/:username`
(⚠️ All protected endpoints require JWT via `Authorization: Bearer `)
---
## 🎯 Roadmap
- [x] JWT session system
- [x] Login, Register, Social Auth
- [x] Patch & Delete `/me`
- [x] Ban, confirm & protect endpoints
- [x] Public profiles `/users/:username`
- [x] API Docs via DSL
- [x] Validation system
- [x] SQLHelper abstraction
- [x] Tag system
- [x] Connections, Likes
- [X] Notifications
- [ ] Commonly used English words should not be accepted as passwords.
- [ ] Real-time messaging (WebSocket or polling)
- [ ] Full CI/CD pipeline
---
## 💡 Philosophy
> 📜 Everything documented
> 🧪 Everything tested
> 🚫 No unhandled JSON
> 💥 No silent failures
> 💎 Code should read like Ruby poetry
---