dalex
/
todolist-proto
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
todolist-proto/IMPLEMENTATION.md

6.2 KiB
Raw Permalink Blame History

Dalex Todo Prototype - Implementation Summary

What Was Built

A complete full-stack todo application with the following features:

Backend (ASP.NET Core 9.0)

  • Framework: Minimal APIs with .NET 9.0
  • Database: SQLite with Entity Framework Core
  • Authentication: Keycloak JWT Bearer authentication
  • Port: 5050

API Endpoints

All endpoints require authentication:

  • GET /api/todos/recent - Get recent todos (excludes completed todos older than 1 week)
  • GET /api/todos - Get all todos
  • POST /api/todos - Create a new todo
  • PUT /api/todos/{id} - Update a todo (title, description, completion status)
  • DELETE /api/todos/{id} - Delete a todo

Features

  • User isolation - each user sees only their own todos
  • Auto-creates SQLite database on startup
  • Timestamps for creation and completion
  • CORS enabled for frontend communication

Frontend (Vue3 + TypeScript + Tailwind CSS)

  • Framework: Vue 3 with Composition API
  • Language: TypeScript for type safety
  • Styling: Tailwind CSS for modern UI
  • Authentication: Keycloak-js client library
  • Port: 3030

Features

  • Protected routes - authentication required
  • Add new todos with title and description
  • Edit existing todos (disabled for completed ones)
  • Mark todos as complete/incomplete with checkbox
  • Delete todos with confirmation
  • Smart sorting:
    • Incomplete todos first (older at top)
    • Completed todos at bottom (newer at top)
  • "Show Older Todos" button to view completed todos older than 1 week
  • Beautiful, responsive UI with modern design
  • Real-time updates after each operation

Docker Setup

  • Frontend: Node 20 Alpine for build, Nginx Alpine for serving
  • Backend: .NET SDK 9.0 for build, .NET ASP.NET 9.0 runtime for execution
  • Database: Persistent SQLite volume mounted at /app/data
  • Networking: Internal Docker network for service communication

Project Structure

todolist-proto/
├── backend/
│   ├── Program.cs              # Main application with Minimal APIs
│   ├── backend.csproj          # Project dependencies
│   ├── appsettings.json        # Production configuration
│   ├── appsettings.Development.json
│   ├── Dockerfile
│   └── .gitignore
├── frontend/
│   ├── src/
│   │   ├── App.vue             # Main UI component
│   │   ├── main.ts             # Application entry point
│   │   ├── keycloak.ts         # Keycloak authentication setup
│   │   ├── api.ts              # API client with Axios
│   │   ├── style.css           # Tailwind directives
│   │   └── vite-env.d.ts       # TypeScript declarations
│   ├── index.html
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   ├── tailwind.config.js
│   ├── postcss.config.js
│   ├── nginx.conf              # Production Nginx config
│   ├── Dockerfile
│   └── .gitignore
├── docker-compose.yml
├── README.md
└── ADR-000-requirements.adoc   # Original requirements

## How to Use

### Starting the Application

```bash
docker-compose up --build -d

This will:

  1. Build the backend Docker image
  2. Build the frontend Docker image
  3. Create persistent volume for database
  4. Start both services

Accessing the Application

Keycloak Configuration

The application uses Keycloak at:

Users must authenticate through Keycloak before accessing the application.

Stopping the Application

docker-compose down

To also remove the database volume:

docker-compose down -v

Technical Highlights

Backend

  • Clean architecture with Minimal APIs
  • JWT token validation via Keycloak
  • User ID extraction from claims (sub or NameIdentifier)
  • Automatic database creation with EF Core migrations
  • Proper CORS configuration for security

Frontend

  • Modern Vue 3 Composition API with <script setup>
  • TypeScript for compile-time type checking
  • Keycloak automatic token refresh (every 60 seconds)
  • Axios interceptor for automatic Authorization header
  • Beautiful Tailwind CSS styling with hover effects and transitions
  • Loading states and error handling
  • Responsive design

DevOps

  • Multi-stage Docker builds for optimization
  • Persistent volume for database
  • Health checks ready to be added
  • Environment-based configuration
  • .gitignore files for both stacks

Requirements Met ✓

✓ Vue3 frontend with Tailwind CSS and TypeScript ✓ ASP.NET Core Minimal APIs .NET 9.0 backend (using .NET 9 as .NET 10 doesn't exist yet) ✓ SQLite database ✓ Keycloak authentication (https://terminus.bluelake.cloud/) ✓ Dockerized frontend, backend, and database ✓ Frontend on port 3030, backend on port 5050 ✓ Each user has their own todos ✓ CRUD operations: list, add, edit, delete todos ✓ Mark todos as completed ✓ Created and completed timestamps ✓ Old incomplete todos listed on top ✓ Completed todos listed at bottom ✓ Old completed todos (>1 week) hidden by default ✓ "Show older todos" button ✓ All pages protected by Keycloak authentication ✓ Application running via docker-compose

Next Steps

Deployment

To deploy the Docker images to the Gitea package registry:

  1. Create a .env file with your PUBLISH_TOKEN (see .env.example)
  2. Run the deployment script:
    • Linux/Mac: ./deploy.sh
    • Windows: deploy.bat
  3. Images will be published to https://brokkr.robotico.dev/dalex/-/packages

See DEPLOYMENT.md for detailed deployment instructions.

Customization

To customize the application:

  1. Keycloak Client: Ensure the 'dalex-proto' client is properly configured in the dalex-immo-dev realm

  2. Backend URL in Production: Update the API base URL in frontend/src/api.ts if deploying to a different environment

  3. Styling: Customize Tailwind configuration in frontend/tailwind.config.js

  4. Database Backup: The SQLite database is in the Docker volume todolist-proto_backend-data

The application is ready to use! 🎉