todolist-proto/README.md

# Dalex Todo Prototype

A full-stack todo application with Vue3 frontend and ASP.NET Core backend, secured with Keycloak authentication.

## Tech Stack

### Frontend
- **Framework**: Vue 3.4+ with Composition API
- **Language**: TypeScript 5.4+
- **Styling**: Tailwind CSS 3.4+
- **Build Tool**: Vite 5.1+
- **HTTP Client**: Axios 1.6+
- **Authentication**: Keycloak-js 25.0+

### Backend
- **Framework**: ASP.NET Core 9.0
- **Architecture**: Minimal APIs
- **Language**: C# with .NET 9.0
- **Database**: SQLite with Entity Framework Core 9.0
- **Authentication**: JWT Bearer (Microsoft.AspNetCore.Authentication.JwtBearer 9.0)

### Infrastructure
- **Containerization**: Docker & Docker Compose
- **Web Server**: Nginx (for frontend production)
- **Authentication Server**: Keycloak
- **Package Registry**: Gitea (https://brokkr.robotico.dev/)

### Development Tools
- **Python**: 3.x (for deployment scripts)
- **Node.js**: 20.x LTS
- **.NET SDK**: 9.0

## Features

- **Frontend**: Vue3 with TypeScript and Tailwind CSS
- **Backend**: ASP.NET Core 9.0 Minimal APIs with SQLite
- **Authentication**: Keycloak integration
- **Containerization**: Docker and Docker Compose

## Prerequisites

- Docker and Docker Compose
- Keycloak server (configured at https://terminus.bluelake.cloud/)

## Getting Started

### Running with Docker Compose

1. Clone the repository
2. Run the application:

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

3. Access the application:
   - Frontend: http://localhost:3030
   - Backend API: http://localhost:5050

### Development Mode

#### Backend

```bash
cd backend
dotnet restore
dotnet run
```

#### Frontend

```bash
cd frontend
npm install
npm run dev
```

## Architecture

### Backend (ASP.NET Core)

- Minimal APIs architecture
- SQLite database for data persistence
- JWT authentication via Keycloak
- RESTful API endpoints for CRUD operations

### Frontend (Vue3)

- TypeScript for type safety
- Tailwind CSS for styling
- Keycloak-js for authentication
- Axios for API calls

## Architecture

### Data Model

The application uses a simple but effective data model with user-isolated todos. For detailed information including:
- Entity relationship diagrams
- Database schema
- Data flow architecture
- Business rules and sorting logic
- Security considerations

See [DATAMODEL.md](DATAMODEL.md) for complete documentation with Mermaid diagrams.

### API Endpoints

- `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
- `DELETE /api/todos/{id}` - Delete a todo

All endpoints require authentication.

## Todo Features

- Add, edit, and delete todos
- Mark todos as completed with timestamps
- Sort todos: incomplete (older first) at top, completed at bottom
- Filter: Hide completed todos older than 1 week (show via button)
- Each user has their own todos (multi-tenant)

## Configuration

### Keycloak

The application is configured to use Keycloak at `https://terminus.bluelake.cloud/` with:
- Realm: `dalex-immo-dev`
- Client ID: `dalex-proto`

### Ports

- Frontend: 3030
- Backend: 5050

## License

MIT

## Deployment

For deploying Docker images to the Gitea package registry at https://brokkr.robotico.dev/dalex/-/packages:

1. Install Python dependencies: `pip install -r requirements.txt`
2. Create `.env` file with your `PUBLISH_TOKEN` (see ENV_SETUP.md)
3. Run: `python deploy.py`

See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed instructions.

## Development

Before deployment, create a `.env` file in the project root:

```bash
PUBLISH_TOKEN=your_gitea_token_here
```

See `.env.example` for template. The `.env` file is git-ignored and will never be overwritten.