Skip to content

README.md

Latest commit

 

History

History
355 lines (253 loc) · 9.91 KB

README.md

File metadata and controls

355 lines (253 loc) · 9.91 KB

Chronos ⏰

A Modern Team Task Management System Inspired by JIRA

License: MIT Angular FastAPI Python Docker

Quick Start • Features • Tech Stack • Deployment • Architecture • Contributing • License

English | 简体中文

📖 Overview

Chronos is a full-stack team task management system inspired by JIRA, designed to help teams plan, track, and deliver projects efficiently. Built with modern technologies, it provides an intuitive interface for managing issues, sprints, backlogs, and roadmaps.

✨ Key Features

  • 📋 Issue Management - Create, track, and manage issues with custom workflows
  • 🏗️ Project Boards - Kanban-style boards for visual task management
  • 📅 Sprint Planning - Plan and track sprints with drag-and-drop simplicity
  • 📊 Backlog Management - Prioritize and organize your product backlog
  • 🗺️ Roadmap View - Visualize project timelines and milestones
  • 📈 Timeline View - Gantt-style timeline for dependency tracking
  • 🎯 Epic Tracking - Group related issues under epics for better organization
  • 🔍 Advanced Filtering - Search and filter issues with custom queries
  • 👥 Team Collaboration - Assign issues, add comments, and collaborate in real-time

🛠️ Tech Stack

Frontend

Technology Version Description
Angular 19.0.0 Modern web framework
TypeScript 5.6.0 Type-safe JavaScript
RxJS 7.8.0 Reactive programming
Angular CLI 19.0.0 Development tooling

Backend

Technology Version Description
Python 3.12 Programming language
FastAPI Latest High-performance API framework
SQLAlchemy Latest ORM for database operations
Dynaconf Latest Configuration management
MySQL Latest Primary database (default)
SQLite - Lightweight alternative
PostgreSQL - Production-ready option

🚀 Getting Started

Quick Start (5 minutes)

The fastest way to get started is using Docker:

# Clone and configure
git clone https://github.com/yourusername/chronos.git
cd chronos
cp .env.example .env

# One-command deployment
docker-compose up -d --build

Access at http://localhost

For detailed quick start guide, see QUICKSTART.md.

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js (v18 or higher) and npm/yarn
  • Python 3.12 or higher
  • uv (Python package manager)
  • MySQL (or SQLite/PostgreSQL as alternative)
  • Docker (for containerized deployment)

Installation

1. Clone the Repository

git clone https://github.com/yourusername/chronos.git
cd chronos

2. Backend Setup

cd Chronos-backend

# Install uv (Python package manager)
pip install uv

# Install dependencies
uv sync

# Configure database settings
cp config/.secrets.toml.example config/.secrets.toml
# Edit config/.secrets.toml with your database credentials

# (Optional) Seed database with initial data
uv run python -m src.scripts.seed

# Start the backend server
uv run uvicorn src.main:app --reload
# Or use: python main.py (if .venv is activated)

Configuration:

  • config/settings.toml - Main configuration (default DB_TYPE = mysql)
  • config/.secrets.toml - Local secrets (copy from .secrets.toml.example)
  • Environment variables with CHRONOS_ prefix can override settings

3. Frontend Setup

cd Chronos-frontend

# Install dependencies
npm install

# Start development server
npm start
# Or: ng serve

# Build for production
npm run build

The frontend will be available at http://localhost:4200

Default Configuration

The backend defaults to MySQL. To use SQLite instead:

  1. Edit config/settings.toml and set DB_TYPE = "sqlite"
  2. No additional configuration needed - SQLite will use a local file

🐳 Docker Deployment (Recommended for Production)

Quick deployment using Docker Compose:

# Clone and configure
cp .env.example .env

# One-command deployment
docker-compose up -d --build

Access the application:

For detailed Docker deployment guide, see docker/README.md.

🏗️ Architecture

Project Structure

chronos/
├── Chronos-backend/          # FastAPI backend
│   ├── src/
│   │   ├── api/v1/          # REST API endpoints
│   │   ├── models/          # SQLAlchemy models
│   │   ├── schemas/         # Pydantic schemas
│   │   ├── services/        # Business logic
│   │   └── database/        # Database configuration
│   ├── config/              # Configuration files
│   └── main.py              # Application entry point
│
├── Chronos-frontend/         # Angular frontend
│   ├── src/
│   │   ├── app/
│   │   │   ├── features/    # Feature modules
│   │   │   ├── services/    # Angular services
│   │   │   ├── shared/      # Shared components
│   │   │   └── layout/      # Layout components
│   │   └── environments/    # Environment configs
│   └── angular.json         # Angular configuration
│
└── README.md                # Project documentation

API Endpoints

The backend provides RESTful APIs:

  • /api/v1/projects - Project management
  • /api/v1/issues - Issue CRUD operations
  • /api/v1/sprints - Sprint management
  • /api/v1/epics - Epic tracking
  • /api/v1/boards - Kanban boards

📸 Screenshots

Add screenshots of your application here:

  • Project Board (Kanban view)
  • Backlog management
  • Sprint planning
  • Timeline/Roadmap view
  • Issue detail page

🐳 Deployment

Quick Deployment with Docker (5 minutes)

# Clone and configure
git clone https://github.com/yourusername/chronos.git
cd chronos
cp .env.example .env

# One-command deployment
docker-compose up -d --build

Access:

Deployment Options

Option Use Case Time Complexity
🐳 Docker Compose Production, Quick Deploy 5 min ⭐
💻 Local Development Development, Debugging 15 min ⭐⭐
☁️ Cloud Platform Large-scale Production 30 min ⭐⭐⭐

Using Deployment Scripts

Linux/Mac:

./docker-deploy.sh start      # Start all services
./docker-deploy.sh status     # Check status
./docker-deploy.sh logs       # View logs
./docker-deploy.sh backup     # Backup database

Windows:

.\docker-deploy.ps1 start     # Start all services
.\docker-deploy.ps1 status    # Check status
.\docker-deploy.ps1 logs      # View logs
.\docker-deploy.ps1 backup    # Backup database

Management Commands

# View service status
docker-compose ps

# View real-time logs
docker-compose logs -f

# Restart services
docker-compose restart

# Stop all services
docker-compose down

# Backup database
docker exec chronos-database mysqldump -u chronos -pchronos_password chronos > backup.sql

For detailed deployment guide, see:

🤝 Contributing

We welcome contributions! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow the existing code style
  • Write meaningful commit messages
  • Add tests for new features
  • Update documentation as needed
  • Ensure all tests pass before submitting PR

Reporting Issues

  • Use GitHub Issues to report bugs or suggest features
  • Provide detailed information about the issue
  • Include steps to reproduce the problem
  • Add screenshots if applicable

📄 License

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

🙏 Acknowledgments

📬 Contact

📚 Documentation

Made with ❤️ by the Chronos Team

Back to top