GoBudget is a REST API developed in Go that allows users to manage their personal budget through financial categories and transactions control. The application uses the Gin framework for API creation and implements authentication via Bearer Token.
The application follows a layered architecture with clear separation of responsibilities:
- Controller: Layer responsible for receiving HTTP requests and returning responses
- Service: Business logic layer
- Repository: Data access layer (Data Access Layer)
- Model: Data models definition layer
- Middleware: Intermediate processing layer (authentication, logging, etc.)
- Router: API routes configuration and definition
HTTP Request → Router → Middleware → Controller → Service → Repository → Database
↓
HTTP Response ← Router ← Middleware ← Controller ← Service ← Repository ← Database
- New user creation
- Login system with JWT token generation
- User deletion
- Custom category creation
- Category listing by user
- Access control through authentication
- Financial transaction recording
- Transaction listing by user
- Transaction association with categories
Description: Creates a new user in the system
Headers:
Content-Type: application/json
Body:
{
"name": "string",
"email": "string",
"password": "string"
}Responses:
201: User created successfully400: Invalid data in request body409: User already exists500: Internal server error
Description: Performs login and returns authentication token
Headers:
Content-Type: application/json
Body:
{
"email": "string",
"password": "string"
}Responses:
200: Login successful{ "token": "jwt_token_string" }400: Invalid data404: User not found500: Internal server error
Description: Creates a new category for the authenticated user
Headers:
Content-Type: application/json
Authorization: Bearer {token}
Body:
{
"name": "string",
"description": "string",
"type": "string"
}Responses:
201: Category created successfully400: Invalid data409: Category already exists500: Internal server error
Description: Lists all categories for the authenticated user
Headers:
Authorization: Bearer {token}
Responses:
200: Category list[ { "id": "string", "name": "string", "description": "string", "type": "string", "user_id": "string" } ]400: Request error500: Internal server error
Description: Creates a new transaction for the authenticated user
Headers:
Content-Type: application/json
Authorization: Bearer {token}
Body:
{
"amount": 0.0,
"description": "string",
"category_id": "string",
"type": "string",
"date": "2024-01-01T00:00:00Z"
}Responses:
201: Transaction created successfully400: Invalid data500: Internal server error
Description: Lists all transactions for the authenticated user
Headers:
Authorization: Bearer {token}
Responses:
200: Transaction list[ { "id": "string", "amount": 0.0, "description": "string", "category_id": "string", "type": "string", "date": "2024-01-01T00:00:00Z", "user_id": "string" } ]400: Request error500: Internal server error
The API uses Bearer Token (JWT) authentication. After logging in through the /users/login endpoint, the returned token must be included in the Authorization header of all requests that require authentication.
Header Format:
Authorization: Bearer {your_jwt_token}
GOBUDGET-API-MAIN/
├── assets/ # Static resources
├── cmd/
│ └── server/
│ └── main.go # Application entry point
├── config/ # Application configuration
│ ├── config.go # Main configuration
│ ├── env.go # Environment variables
│ ├── jwt.go # JWT configuration
│ ├── logger.go # Logger configuration
│ ├── postgres.go # PostgreSQL configuration
│ └── validator.go # Custom validators
├── db/
│ └── migrations/ # Database migrations
│ ├── 000001_init_schema.down.sql
│ └── 000001_init_schema.up.sql
├── internal/
│ ├── controller/ # HTTP controllers layer
│ │ ├── category.go # Category controller
│ │ ├── transaction.go # Transaction controller
│ │ └── user.go # User controller
│ ├── docs/ # Swagger documentation
│ │ ├── docs.go
│ │ ├── swagger.json
│ │ └── swagger.yaml
│ ├── middleware/ # Application middlewares
│ │ └── auth.go # Authentication middleware
│ ├── model/ # Data models
│ │ ├── category.go # Category model
│ │ ├── transaction.go # Transaction model
│ │ └── user.go # User model
│ ├── repository/ # Data access layer
│ │ ├── category.go # Category repository
│ │ ├── transaction.go # Transaction repository
│ │ └── user.go # User repository
│ ├── router/ # Route configuration
│ │ ├── router.go # Main router
│ │ └── routes.go # Route definitions
│ ├── service/ # Business logic layer
│ │ ├── category.go # Category service
│ │ ├── transaction.go # Transaction service
│ │ └── user.go # User service
│ └── utils/ # Utilities
├── scripts/ # Helper scripts
├── tests/ # Automated tests
├── .air.toml # Air configuration (hot reload)
├── .gitignore # Git ignored files
├── docker-compose.yml # Docker Compose configuration
├── Dockerfile # Application Docker image
├── go.mod # Go dependencies
├── go.sum # Dependencies checksums
├── LICENSE # Project license
├── main.go # Alternative main file
├── makefile # Make commands
├── mise.toml # Mise configuration
└── README.md # Project documentation
The API returns standardized errors with appropriate HTTP codes and descriptive messages. All errors follow the format:
{
"error": "Error description",
"code": 400
}The system implements structured logging to facilitate debugging and monitoring:
- Debug: Detailed information for development
- Error: Critical errors that require attention
- Go: Programming language
- Gin: Web framework for Go
- PostgreSQL: Relational database
- JWT: Token-based authentication
- Swagger: Automatic API documentation
- Docker: Application containerization
- Air: Hot reload for development
- Mise: Development tools manager
The API is documented using Swagger annotations, allowing automatic generation of interactive documentation. Annotations include:
- Endpoint descriptions
- Model schemas
- Response codes
- Authentication requirements
The application uses PostgreSQL as the main database. Migrations are managed through SQL files in the db/migrations/ folder.
- 000001_init_schema.up.sql: Initial table creation
- 000001_init_schema.down.sql: Initial table rollback
Based on the models, the main tables are:
- users: User storage
- categories: Transaction categories by user
- transactions: User financial transactions
- Go 1.21+
- PostgreSQL 13+
- Docker (optional)
- Air (for hot reload)
-
Clone the repository:
git clone https://github.com/breno5g/GoBudget.git cd GoBudget -
Configure environment variables:
# Copy the example file and edit the configurations cp .env.example .env -
Run migrations:
make migrate-up
-
Run the application:
# Development (with hot reload) make dev # Production make build make run
To run with Docker:
# Start services
docker-compose up -d
# Access the application at http://localhost:8080The project includes a Makefile with useful commands:
make build # Compile the application
make run # Run the application
make dev # Run in development mode
make test # Run tests
make migrate-up # Run migrations
make migrate-down # Rollback migrations
make clean # Clean temporary filesInteractive API documentation is available at:
- Development: http://localhost:8080/swagger/index.html
- Production: https://your-api.com/swagger/index.html
To use this API, you can:
- Implement a web or mobile client
- Add features like financial reports
- Implement advanced transaction filters
- Add multi-currency support
- Create data visualization dashboards
- All passwords must be hashed before storage
- JWT tokens should have appropriate expiration time
- Strict input data validation through middlewares
- Rate limiting to prevent API abuse
- HTTPS mandatory in production
- Authentication middleware protects sensitive routes
- Input data validation with custom validators
- Fork the project
- Create a branch for your feature (
git checkout -b feature/new-feature) - Commit your changes (
git commit -am 'Add new feature') - Push to the branch (
git push origin feature/new-feature) - Open a Pull Request
This project is under the license specified in the LICENSE file.