A Kotlin-based REST API for personal expense and income tracking, built with Ktor framework and PostgreSQL database.
- User Management: Registration and authentication with JWT tokens
- Expense Tracking: Create, read, update, and delete expenses with categories
- Income Tracking: Manage recurring and one-time income entries
- Date Range Filtering: Filter expenses and income by date ranges
- Recurring Transactions: Support for recurring expenses and income
- RESTful API: Clean REST endpoints for all operations
- Database Migrations: Automated schema management with Flyway
- Docker Support: Containerized deployment with Docker Compose
- Backend: Kotlin with Ktor framework
- Database: PostgreSQL with Exposed ORM
- Migrations: Flyway for database schema management
- Authentication: JWT tokens
- Containerization: Docker & Docker Compose
- Build Tool: Gradle with Shadow JAR plugin
- Docker and Docker Compose
- Java 17+ (for local development)
- Gradle (for local development)
-
Clone the repository
git clone <your-repo-url> cd ExpenseTracker
-
Start the application
docker-compose up --build
-
Access the API
- The API will be available at
http://localhost:8081 - PostgreSQL database runs on port
5432
- The API will be available at
-
Set up PostgreSQL database
docker-compose up db
-
Build the project
./gradlew build
-
Run the application
./gradlew run
curl -X POST http://localhost:8081/auth/register \
-H "Content-Type: application/json" \
-d '{
"username": "testuser",
"email": "test@example.com",
"password": "password123",
"registrationCode": "WEYRICK2025"
}'curl -X POST http://localhost:8081/auth/login \
-H "Content-Type: application/json" \
-d '{
"username": "testuser",
"password": "password123"
}'curl -X POST http://localhost:8081/expenses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"amount": 50.00,
"category": "FOOD",
"description": "Lunch",
"isRecurring": false,
"startDate": "2024-01-15"
}'curl -X GET http://localhost:8081/expenses \
-H "Authorization: Bearer YOUR_JWT_TOKEN"curl -X PUT http://localhost:8081/expenses/{expense_id} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"amount": 60.00,
"category": "FOOD",
"description": "Updated lunch",
"isRecurring": false,
"startDate": "2024-01-15"
}'curl -X DELETE http://localhost:8081/expenses/{expense_id} \
-H "Authorization: Bearer YOUR_JWT_TOKEN"curl -X POST http://localhost:8081/incomes \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
"amount": 5000.00,
"description": "Salary",
"isRecurring": true,
"startDate": "2024-01-01",
"endDate": "2024-12-31"
}'curl -X GET http://localhost:8081/incomes \
-H "Authorization: Bearer YOUR_JWT_TOKEN"id(UUID, Primary Key)username(VARCHAR, Unique)email(VARCHAR, Unique)password_hash(VARCHAR)created_at(TIMESTAMP)
id(UUID, Primary Key)user_id(UUID, Foreign Key to Users)amount(DECIMAL)category(VARCHAR)description(TEXT)is_recurring(BOOLEAN)start_date(DATE)end_date(DATE, Nullable)
id(UUID, Primary Key)user_id(UUID, Foreign Key to Users)amount(DECIMAL)description(TEXT)is_recurring(BOOLEAN)start_date(DATE)end_date(DATE, Nullable)
The application can be configured using environment variables or the application.conf file:
db.jdbcurl: Database connection URLdb.user: Database usernamedb.password: Database passwordjwt.secret: JWT signing secretjwt.issuer: JWT issuerjwt.audience: JWT audiencejwt.expiresIn: JWT expiration time
The docker-compose.yml file includes:
- PostgreSQL database service
- Application service with proper networking
- Environment variable configuration
- Volume persistence for database data
Run the test suite:
./gradlew testCreate a fat JAR for deployment:
./gradlew shadowJarThe JAR file will be created at build/libs/ExpenseTracker-all.jar
docker-compose up -d- Build the JAR:
./gradlew shadowJar - Set up PostgreSQL database
- Run:
java -jar build/libs/ExpenseTracker-all.jar
This project is licensed under the MIT License - see the LICENSE file for details.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Submit a pull request
For issues and questions, please open an issue on GitHub.