148 lines
4.1 KiB
Markdown
148 lines
4.1 KiB
Markdown
# Time Tracker Backend
|
|
|
|
This is the backend service for the Time Tracker application, built with Go, Gin, and GORM.
|
|
|
|
## Database Setup
|
|
|
|
The application uses PostgreSQL as its database. The database connection is configured using GORM, a popular Go ORM library.
|
|
|
|
### Configuration
|
|
|
|
Database configuration is handled through the `models.DatabaseConfig` struct in `internal/models/db.go`. The application uses sensible defaults that can be overridden with environment variables:
|
|
|
|
- `DB_HOST`: Database host (default: "localhost")
|
|
- `DB_PORT`: Database port (default: 5432)
|
|
- `DB_USER`: Database user (default: "timetracker")
|
|
- `DB_PASSWORD`: Database password (default: "password")
|
|
- `DB_NAME`: Database name (default: "timetracker")
|
|
- `DB_SSLMODE`: SSL mode (default: "disable")
|
|
|
|
### Running with Docker
|
|
|
|
The easiest way to run the database is using Docker Compose:
|
|
|
|
```bash
|
|
# Start the database
|
|
docker-compose up -d db
|
|
|
|
# Check if the database is running
|
|
docker-compose ps
|
|
```
|
|
|
|
### Database Migrations
|
|
|
|
The application automatically migrates the database schema on startup using GORM's AutoMigrate feature. This creates all necessary tables based on the model definitions.
|
|
|
|
### Initial Data Seeding
|
|
|
|
The application seeds the database with initial data if it's empty. This includes:
|
|
|
|
- A default company
|
|
- An admin user with email "admin@example.com" and password "Admin@123456"
|
|
|
|
## Running the Application
|
|
|
|
### Using Make Commands
|
|
|
|
The project includes a Makefile with common commands:
|
|
|
|
```bash
|
|
# Start the database
|
|
make db-start
|
|
|
|
# Test the database connection
|
|
make db-test
|
|
|
|
# Run database migrations
|
|
make migrate
|
|
|
|
# Seed the database with initial data
|
|
make seed
|
|
|
|
# Test the database models
|
|
make model-test
|
|
|
|
# Run the application
|
|
make run
|
|
|
|
# Build the application
|
|
make build
|
|
|
|
# Show all available commands
|
|
make help
|
|
```
|
|
|
|
### Manual Commands
|
|
|
|
If you prefer not to use Make, you can run the commands directly:
|
|
|
|
```bash
|
|
# Start the database
|
|
cd /path/to/timetracker
|
|
docker-compose up -d db
|
|
|
|
# Test the database connection
|
|
cd backend
|
|
go run cmd/dbtest/main.go
|
|
|
|
# Run database migrations
|
|
cd backend
|
|
go run cmd/migrate/main.go
|
|
|
|
# Seed the database with initial data
|
|
cd backend
|
|
go run cmd/seed/main.go
|
|
|
|
# Run the backend application
|
|
cd backend
|
|
go run cmd/api/main.go
|
|
```
|
|
|
|
The API will be available at http://localhost:8080/api and the Swagger documentation at http://localhost:8080/swagger/index.html.
|
|
|
|
### Environment Variables
|
|
|
|
You can configure the database connection using environment variables:
|
|
|
|
```bash
|
|
# Example: Connect to a different database
|
|
DB_HOST=my-postgres-server DB_PORT=5432 DB_USER=myuser DB_PASSWORD=mypassword DB_NAME=mydb go run cmd/api/main.go
|
|
```
|
|
|
|
## Database Models
|
|
|
|
The application uses the following models:
|
|
|
|
- `User`: Represents a user in the system
|
|
- `Company`: Represents a company
|
|
- `Customer`: Represents a customer
|
|
- `Project`: Represents a project
|
|
- `Activity`: Represents an activity
|
|
- `TimeEntry`: Represents a time entry
|
|
|
|
Each model has corresponding CRUD operations and relationships defined in the `internal/models` directory.
|
|
|
|
## GORM Best Practices
|
|
|
|
The application follows these GORM best practices:
|
|
|
|
1. **Connection Pooling**: Configured with sensible defaults for maximum idle connections, maximum open connections, and connection lifetime.
|
|
|
|
2. **Migrations**: Uses GORM's AutoMigrate to automatically create and update database tables.
|
|
|
|
3. **Transactions**: Uses transactions for operations that require multiple database changes to ensure data consistency.
|
|
|
|
4. **Soft Deletes**: Uses GORM's soft delete feature to mark records as deleted without actually removing them from the database.
|
|
|
|
5. **Relationships**: Properly defines relationships between models using GORM's relationship features.
|
|
|
|
6. **Error Handling**: Properly handles database errors and returns appropriate error messages.
|
|
|
|
7. **Context Support**: Uses context for database operations to support timeouts and cancellation.
|
|
|
|
8. **Logging**: Configures GORM's logger for appropriate logging based on the environment.
|
|
|
|
9. **Graceful Shutdown**: Properly closes database connections when the application shuts down.
|
|
|
|
10. **Validation**: Implements validation for model fields before saving to the database.
|