�STARK Todo List

A minimalist, modern, and highly polished Todo List application built with Next.js

English | 简体中文

STARK Todo List Preview

---

🎯 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

• âš™ï¸<EFBFBD> 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)

• ðŸ”<EFBFBD> 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

   git clone https://github.com/yourusername/stark-todo-list.git
   cd stark-todo-list
   

2. Install dependencies

   npm install
   # or
   pnpm install
   

3. Start development server

   npm run dev
   # or
   pnpm dev
   

4. Open your browser

   http://localhost:2333
   

Option 2: Using Management Script

A convenient shell script is provided for easy management:

# 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)

   ./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)

   ./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)

   # 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

   # Start with Docker Compose
   docker compose up -d --build
   
   # View logs
   docker compose logs -f
   

5. Access the application

   http://localhost:4000
   

6. Management commands

   # Stop containers
   docker compose down
   
   # Restart containers
   docker compose restart
   
   # View logs
   docker compose logs -f
   
   # Quick update (rebuild everything)
   ./docker-update.sh
   

7. 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:

     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:

     docker run --rm -v stark-todo-list_todos-data:/data -v $(pwd):/backup alpine tar xzf /backup/todos-backup.tar.gz -C /data
     

8. Clean up (removes data)

   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

ðŸ“<EFBFBD> Data Format

Tasks are stored in todos.json with the following structure:

[
  {
    "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:

# 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	â<EFBFBD>?	Get all active todos
POST	�	Create a new todo
PUT	�	Update an existing todo
DELETE	�	Soft delete a todo

GET /api/todos

curl https://your-domain/api/todos

POST /api/todos

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

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

curl -X DELETE "https://your-domain/api/todos?id=uuid" \
  -H "X-API-Key: stark123"

Groups API (/api/groups)

Method	Auth	Description
GET	â<EFBFBD>?	Get all groups
POST	�	Create a new group
DELETE	�	Delete a group

GET /api/groups

curl https://your-domain/api/groups

POST /api/groups

curl -X POST https://your-domain/api/groups \
  -H "Content-Type: application/json" \
  -H "X-API-Key: stark123" \
  -d '{"name": "Work"}'

DELETE /api/groups

curl -X DELETE "https://your-domain/api/groups?id=uuid" \
  -H "X-API-Key: stark123"

Stats API (/api/stats)

Method	Auth	Description
GET	â<EFBFBD>?	Get PV/UV statistics
POST	â<EFBFBD>?	Update visit statistics

GET /api/stats

curl https://your-domain/api/stats

Auth API (/api/auth)

Method	Auth	Description
POST	â<EFBFBD>?	Verify password

POST /api/auth

curl -X POST https://your-domain/api/auth \
  -H "Content-Type: application/json" \
  -d '{"password": "stark123"}'

ðŸ¤<EFBFBD> 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.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

ðŸ™<EFBFBD> Acknowledgments

• Powered by Next.js
• UI Design inspired by modern minimalism
• Built with â<>¤ï¸<C3AF> by the STARK

---

�Back to Top

Made with â<>¤ï¸<C3AF> by STARK | Powered by Next.js