kilo-cv/README.md

CV - Tuan-Dat Tran

A modern, minimalist CV/Resume single-page application with admin panel and persistent storage.

Architecture

┌─────────────────────────────────────────────────────┐
│                 Docker Compose                       │
│  ┌──────────────┐    ┌──────────────────────────┐   │
│  │   Frontend   │    │      Backend API         │   │
│  │   (React)    │───▶│   (Express.js)           │   │
│  │   Port 5173  │    │   Port 3001              │   │
│  └──────────────┘    └───────────┬──────────────┘   │
│                                  │                   │
│                      ┌───────────▼──────────────┐   │
│                      │      SQLite DB           │   │
│                      │   (Volume: ./data)       │   │
│                      └──────────────────────────┘   │
└─────────────────────────────────────────────────────┘

Features

• Modern, responsive design
• Smooth scroll animations with Framer Motion
• Admin panel for CV editing (password protected)
• Persistent storage with SQLite
• Docker Compose deployment
• RESTful API with OpenAPI documentation
• Optional Keycloak integration for SSO
• Automated releases with semantic-release

Tech Stack

Frontend

• React 19 - UI Library
• Vite 7 - Build Tool
• Tailwind CSS 4 - Styling
• Framer Motion 12 - Animations
• Lucide React - Icons

Backend

• Express.js 4 - API Server
• Knex.js - SQL Query Builder
• SQLite with better-sqlite3 - Database

Getting Started

Prerequisites

• Node.js 20+
• npm 10+
• Docker & Docker Compose (optional)

Option 1: Docker Compose (Recommended)

# Start all services
docker-compose up -d

# Frontend: http://localhost:5173
# Backend API: http://localhost:3001
# Admin Panel: http://localhost:5173/admin
# API Docs: http://localhost:3001/api/docs

Option 2: Local Development

# Install frontend dependencies
npm install

# Install backend dependencies
cd backend && npm install && cd ..

# Start backend (terminal 1)
cd backend && npm run dev

# Start frontend (terminal 2)
npm run dev

Environment Variables

Backend (backend/.env):

PORT=3001
DB_PATH=./data/cv.db
AUTH_MODE=simple
# Keycloak settings (required if AUTH_MODE=keycloak)
KEYCLOAK_URL=https://keycloak.example.com
KEYCLOAK_REALM=your-realm
KEYCLOAK_CLIENT_ID=cv-app

Development Setup

Pre-commit Setup

This project uses:

• ESLint for code linting
• commitlint for commit message validation
• Husky for git hooks
• Gitleaks for secret scanning

Install Gitleaks before committing:

# macOS
brew install gitleaks

# Linux
curl -sSfL https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks_linux_x64.tar.gz | tar -xz
sudo mv gitleaks /usr/local/bin/

# Windows
scoop install gitleaks

Commit Guidelines

This project uses Conventional Commits:

<type>(<scope>): <description>

# Examples:
feat(ui): add export button
fix(api): resolve authentication issue
docs(readme): update installation steps

API Documentation

Interactive Swagger UI available at: http://localhost:3001/api/docs

Admin Authentication

Simple Mode (Default)

• Random password generated on server startup
• Password displayed in console logs
• JWT token-based authentication

Keycloak Mode

• SSO integration via Keycloak
• Configure via AUTH_MODE=keycloak and related environment variables

Documentation

Document	Description
Architecture	System architecture and design patterns
Release Engineering	Release and deployment documentation

License

MIT License - see LICENSE for details.