---
## 🎯 Features
- **🎨 Modern UI/UX Design**
- Beautiful animated logo with smooth transitions
- Glassmorphism cards with backdrop blur effects
- Smooth animations powered by Framer Motion
- Color-coded task statistics (Blue, Orange, Green)
- **🌓 Theme Support**
- Light mode with vibrant gradients
- Dark mode with professional aesthetics
- System preference detection
- Seamless theme switching
- **📱 Responsive Design**
- Desktop-optimized with top navigation tabs
- Mobile-friendly with bottom navigation bar
- Touch-optimized interactive elements
- Adaptive layouts for all screen sizes
- **⚙️ Customization**
- Multi-language support (English & Chinese)
- Customizable logo text
- Timezone selection
- Theme mode preferences
- **📊 Task Management**
- Create, complete, and delete tasks
- Task creation and completion timestamps
- Soft deletion (logical delete with data preservation)
- Filter tasks by status (All, Active, Completed)
- **📊 Interactive Analytics Dashboard**
- Daily Activity trend charts (Creation vs Completion)
- Task completion timeline (Gantt-style visual)
- Real-time KPI statistics (Total, Completed, Success Rate)
- Flexible date ranges (7 Days, 30 Days, All Time)
- **🔐 Access Control**
- Password-protected task operations (add, edit, delete)
- Client-side authentication persistence
- Configurable password via environment variable
- **💾 Data Persistence**
- Local JSON storage (no database required)
- Data survives app restarts
- Fully traceable task history
## 🚀 Quick Start
### Prerequisites
- Node.js 18+ (for local development)
- Docker (optional, for containerized deployment)
### Option 1: Local Development (Recommended)
1. **Clone the repository**
```bash
git clone https://github.com/yourusername/stark-todo-list.git
cd stark-todo-list
```
2. **Install dependencies**
```bash
npm install
# or
pnpm install
```
3. **Start development server**
```bash
npm run dev
# or
pnpm dev
```
4. **Open your browser**
```
http://localhost:3000
```
### Option 2: Using Management Script
A convenient shell script is provided for easy management:
```bash
# Start the application
./run.sh start
# Stop the application
./run.sh stop
# Restart with cache cleanup
./run.sh restart
# View logs
./run.sh logs
# Check status
./run.sh status
```
### Option 3: Docker Deployment
1. **Using the Docker startup script (Recommended)**
```bash
./docker-start.sh
```
The script will:
- Build and start the Docker container
- Automatically display backend logs
- Use Docker volume for data persistence
2. **Quick update (rebuild and restart)**
```bash
./docker-update.sh
```
This script will:
- Stop the current container
- Pull latest code (if Git repository)
- Rebuild the Docker image (no cache)
- Start the new container
- Display logs automatically
3. **Configure authentication password (optional)**
```bash
# Set custom password via environment variable
export AUTH_PASSWORD=your_custom_password
# Or create a .env file
echo "AUTH_PASSWORD=your_custom_password" > .env
```
> Default password is `stark123` if not configured.
4. **Or manually with Docker Compose**
```bash
# Start with Docker Compose
docker compose up -d --build
# View logs
docker compose logs -f
```
3. **Access the application**
```
http://localhost:4000
```
4. **Management commands**
```bash
# Stop containers
docker compose down
# Restart containers
docker compose restart
# View logs
docker compose logs -f
# Quick update (rebuild everything)
./docker-update.sh
```
5. **Data Persistence & Safe Updates**
- Data is stored in a Docker volume named `todos-data`, which persists `todos.json` and `stats.json`.
- **Important**: Always use `./docker-update.sh` for updates. Avoid running `docker compose down -v` manually, as the `-v` flag will permanently delete your data volumes.
- To backup data:
```bash
docker run --rm -v stark-todo-list_todos-data:/data -v $(pwd):/backup alpine tar czf /backup/todos-backup.tar.gz -C /data .
```
- To restore data:
```bash
docker run --rm -v stark-todo-list_todos-data:/data -v $(pwd):/backup alpine tar xzf /backup/todos-backup.tar.gz -C /data
```
6. **Clean up (removes data)**
```bash
docker compose down -v
```
## 📂 Project Structure
```
stark-todo-list/
├── src/
│ ├── app/ # Next.js App Router
│ │ ├── api/ # API Routes
│ │ │ └── todos/ # Todo CRUD endpoints
│ │ ├── analytics/ # Insights & Charts page
│ │ ├── settings/ # Settings page
│ │ ├── page.tsx # Main page
│ │ ├── layout.tsx # Root layout
│ │ └── globals.css # Global styles
│ ├── components/ # React components
│ │ ├── StarkLogo.tsx # Animated logo
│ │ └── AnalyticsDashboard.tsx # Data visualization
│ ├── contexts/ # React contexts
│ │ └── SettingsContext.tsx
│ ├── lib/ # Utility functions
│ │ ├── storage.ts # JSON file operations
│ │ ├── translations.ts # i18n translations
│ │ └── timezones.ts # Timezone data
│ └── ...
├── public/ # Static assets
├── scripts/
│ ├── generate-icons.js # Favicon generator
│ └── generate-mock-data.js # Demo data generator
├── docker-compose.yml # Docker Compose config
├── Dockerfile # Docker image config
├── run.sh # Management script
├── docker-start.sh # Docker startup script
├── todos.json # Data storage file
└── package.json # Project dependencies
```
## 🛠️ Technology Stack
- **Framework**: Next.js 15 (App Router)
- **Language**: TypeScript 5
- **Styling**: Tailwind CSS 3.4
- **Animation**: Framer Motion
- **Charts**: Recharts
- **Icons**: Lucide React
- **Containerization**: Docker & Docker Compose
## 📝 Data Format
Tasks are stored in `todos.json` with the following structure:
```json
[
{
"id": "uuid",
"text": "Task description",
"completed": false,
"createdAt": 1705392000000,
"completedAt": null,
"deleted": false,
"deletedAt": null,
"groupId": "default",
"priority": "P2"
}
]
```
## 🔌 API Reference
The application provides a RESTful API for programmatic access. View the interactive API documentation at `/api-docs` in your browser.
### Authentication
Protected endpoints require authentication via API key in request headers:
```bash
# Option 1: X-API-Key header
-H "X-API-Key: your_password"
# Option 2: Authorization Bearer header
-H "Authorization: Bearer your_password"
```
> Default password is `stark123`. Configure via `AUTH_PASSWORD` environment variable.
### Endpoints
#### Todos API (`/api/todos`)
| Method | Auth | Description |
|--------|------|-------------|
| GET | ❌ | Get all active todos |
| POST | ✅ | Create a new todo |
| PUT | ✅ | Update an existing todo |
| DELETE | ✅ | Soft delete a todo |
**GET /api/todos**
```bash
curl https://your-domain/api/todos
```
**POST /api/todos**
```bash
curl -X POST https://your-domain/api/todos \
-H "Content-Type: application/json" \
-H "X-API-Key: stark123" \
-d '{"text": "New task", "groupId": "default", "priority": "P1"}'
```
**PUT /api/todos**
```bash
curl -X PUT https://your-domain/api/todos \
-H "Content-Type: application/json" \
-H "X-API-Key: stark123" \
-d '{"id": "uuid", "completed": true, "text": "Updated text"}'
```
**DELETE /api/todos**
```bash
curl -X DELETE "https://your-domain/api/todos?id=uuid" \
-H "X-API-Key: stark123"
```
#### Groups API (`/api/groups`)
| Method | Auth | Description |
|--------|------|-------------|
| GET | ❌ | Get all groups |
| POST | ✅ | Create a new group |
| DELETE | ✅ | Delete a group |
**GET /api/groups**
```bash
curl https://your-domain/api/groups
```
**POST /api/groups**
```bash
curl -X POST https://your-domain/api/groups \
-H "Content-Type: application/json" \
-H "X-API-Key: stark123" \
-d '{"name": "Work"}'
```
**DELETE /api/groups**
```bash
curl -X DELETE "https://your-domain/api/groups?id=uuid" \
-H "X-API-Key: stark123"
```
#### Stats API (`/api/stats`)
| Method | Auth | Description |
|--------|------|-------------|
| GET | ❌ | Get PV/UV statistics |
| POST | ❌ | Update visit statistics |
**GET /api/stats**
```bash
curl https://your-domain/api/stats
```
#### Auth API (`/api/auth`)
| Method | Auth | Description |
|--------|------|-------------|
| POST | ❌ | Verify password |
**POST /api/auth**
```bash
curl -X POST https://your-domain/api/auth \
-H "Content-Type: application/json" \
-d '{"password": "stark123"}'
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
For more details, see [CONTRIBUTING.md](CONTRIBUTING.md).
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Powered by [Next.js](https://nextjs.org/)
- UI Design inspired by modern minimalism
- Built with ❤️ by the STARK
---
**[⬆ Back to Top](#-stark-todo-list)**
Made with ❤️ by STARK | Powered by Next.js
**A minimalist, modern, and highly polished Todo List application built with Next.js**
[English](README.md) | [简体中文](README.zh-CN.md)
[STARK Todo List Preview](https://todo.unistark.dpdns.org/)