Internal
Public Access
Add comprehensive README.md documentation
Added detailed documentation covering: - Feature overview and capabilities - Installation and quick start guide - Configuration options and environment setup - API documentation and endpoints - Project structure explanation - Docker deployment instructions - Database model descriptions - Development guidelines - Production deployment checklist - Mobile app integration details 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Keith Smith
co-authored by
Claude Sonnet 4.5
Claude Sonnet 4.5
parent
6a0b35c39c
commit
7f7ea3fef4
@@ -0,0 +1,348 @@
|
||||
# KeepItGoing Server
|
||||
|
||||
A powerful Django-based task management system with time tracking, tag organization, and real-time collaboration features.
|
||||
|
||||
## Features
|
||||
|
||||
### Task Management
|
||||
- **Hierarchical Tasks**: Support for parent tasks and subtasks
|
||||
- **Priority Levels**: Low, Medium, High, and Urgent
|
||||
- **Status Tracking**: Pending, In Progress, Completed, Cancelled
|
||||
- **Due Dates & Times**: Set specific due dates and times for tasks
|
||||
- **Recurrence**: Daily, Weekly, Bi-weekly, Monthly, Yearly, and Custom patterns
|
||||
|
||||
### Organization
|
||||
- **Tag-Based System**: Organize tasks with multiple colored tags
|
||||
- **Smart Filtering**: View tasks by All, Today, Upcoming, Overdue, or Completed
|
||||
- **Auto-Tag Assignment**: New tasks automatically inherit the active filter tag
|
||||
- **Flexible Sorting**: Sort by due date (earliest/latest) or priority (high-to-low/low-to-high)
|
||||
|
||||
### Time Tracking
|
||||
- **Start/Stop Timers**: Built-in time tracking for tasks
|
||||
- **Time Entry History**: View detailed time logs for each task
|
||||
- **Formatted Display**: Time shown as H:MM:SS with visual indicators
|
||||
- **Running Timer Display**: Always visible timer in the UI when tracking time
|
||||
|
||||
### Collaboration
|
||||
- **Task Sharing**: Share individual tasks or entire tags with other users
|
||||
- **Multi-user Support**: Full authentication and user management
|
||||
- **Shared Views**: See tasks shared with you alongside your own
|
||||
|
||||
### User Interface
|
||||
- **3-Pane Layout**: Sidebar navigation, task list, and detail panel
|
||||
- **Responsive Design**: Works on desktop, tablet, and mobile
|
||||
- **Dark Mode**: Built-in dark/light theme toggle
|
||||
- **Quick Add**: Fast task creation from any filter view
|
||||
- **Inline Actions**: Toggle completion, start/stop timers without leaving the list
|
||||
|
||||
### API & Sync
|
||||
- **RESTful API**: Full REST API for programmatic access
|
||||
- **Mobile App Support**: Sync protocol for Android app
|
||||
- **Real-time Updates**: Task changes sync across devices
|
||||
- **Conflict Resolution**: Handles offline changes and syncing
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Backend**: Django 5.x, Django REST Framework
|
||||
- **Database**: SQLite (development), PostgreSQL-compatible
|
||||
- **Task Queue**: Celery with Redis
|
||||
- **Authentication**: JWT tokens with session support
|
||||
- **Frontend**: HTML5, CSS3, Vanilla JavaScript
|
||||
- **Deployment**: Docker support included
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
- Python 3.12+
|
||||
- pip
|
||||
- virtualenv (recommended)
|
||||
|
||||
### Quick Start
|
||||
|
||||
1. **Clone the repository**
|
||||
```bash
|
||||
git clone https://git.firebugit.com/Firebug_IT/KeepItGoingServer.git
|
||||
cd KeepItGoingServer
|
||||
```
|
||||
|
||||
2. **Create virtual environment**
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
```
|
||||
|
||||
3. **Install dependencies**
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
4. **Configure environment**
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings
|
||||
```
|
||||
|
||||
5. **Run migrations**
|
||||
```bash
|
||||
export DJANGO_SETTINGS_MODULE=config.settings.development
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
6. **Create superuser**
|
||||
```bash
|
||||
python manage.py createsuperuser
|
||||
```
|
||||
|
||||
7. **Run development server**
|
||||
```bash
|
||||
python manage.py runserver
|
||||
```
|
||||
|
||||
8. **Access the application**
|
||||
- Web Interface: http://localhost:8000
|
||||
- Admin Panel: http://localhost:8000/admin
|
||||
- API Root: http://localhost:8000/api/
|
||||
|
||||
## Configuration
|
||||
|
||||
### Settings Modules
|
||||
|
||||
The project uses different settings modules for different environments:
|
||||
|
||||
- `config.settings.development` - Local development
|
||||
- `config.settings.production` - Production deployment
|
||||
- `config.settings.selfhosted` - Self-hosted instances
|
||||
|
||||
Set via environment variable:
|
||||
```bash
|
||||
export DJANGO_SETTINGS_MODULE=config.settings.development
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Key environment variables (see `.env.example`):
|
||||
|
||||
- `SECRET_KEY` - Django secret key (required in production)
|
||||
- `DEBUG` - Enable debug mode (True/False)
|
||||
- `ALLOWED_HOSTS` - Comma-separated list of allowed hosts
|
||||
- `DATABASE_URL` - Database connection string
|
||||
- `REDIS_URL` - Redis connection for Celery
|
||||
- `CSRF_TRUSTED_ORIGINS` - HTTPS origins for CSRF
|
||||
|
||||
## API Documentation
|
||||
|
||||
### Authentication
|
||||
|
||||
The API supports both session-based and token-based authentication.
|
||||
|
||||
**Get Token:**
|
||||
```bash
|
||||
POST /api/auth/login/
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "password"
|
||||
}
|
||||
```
|
||||
|
||||
**Use Token:**
|
||||
```bash
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### Endpoints
|
||||
|
||||
#### Tasks
|
||||
- `GET /api/tasks/` - List all tasks
|
||||
- `POST /api/tasks/` - Create task
|
||||
- `GET /api/tasks/{id}/` - Get task details
|
||||
- `PUT /api/tasks/{id}/` - Update task
|
||||
- `DELETE /api/tasks/{id}/` - Delete task
|
||||
|
||||
#### Tags
|
||||
- `GET /api/tags/` - List all tags
|
||||
- `POST /api/tags/` - Create tag
|
||||
- `GET /api/tags/{id}/` - Get tag details
|
||||
- `PUT /api/tags/{id}/` - Update tag
|
||||
- `DELETE /api/tags/{id}/` - Delete tag
|
||||
|
||||
#### Time Entries
|
||||
- `GET /api/time-entries/` - List time entries
|
||||
- `POST /api/time-entries/` - Create time entry
|
||||
- `POST /api/tasks/{id}/start-timer/` - Start timer
|
||||
- `POST /api/time-entries/{id}/stop/` - Stop timer
|
||||
|
||||
#### Sync (Mobile)
|
||||
- `POST /api/sync/sync/` - Bidirectional sync endpoint
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
keepitgoing-server/
|
||||
├── config/ # Project configuration
|
||||
│ ├── settings/ # Environment-specific settings
|
||||
│ ├── urls.py # Main URL configuration
|
||||
│ └── wsgi.py # WSGI entry point
|
||||
├── tasks/ # Task management app
|
||||
│ ├── models.py # Task, Tag, TimeEntry models
|
||||
│ ├── views.py # API and web views
|
||||
│ ├── serializers.py # DRF serializers
|
||||
│ └── migrations/ # Database migrations
|
||||
├── users/ # User management app
|
||||
├── sync/ # Mobile sync app
|
||||
├── notifications/ # Notification system
|
||||
├── templates/ # Django templates
|
||||
│ ├── base.html # Base template
|
||||
│ └── tasks/ # Task templates
|
||||
├── static/ # Static files
|
||||
│ ├── css/ # Stylesheets
|
||||
│ └── js/ # JavaScript
|
||||
├── manage.py # Django management script
|
||||
└── requirements.txt # Python dependencies
|
||||
```
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
### Development
|
||||
```bash
|
||||
docker-compose -f docker-compose.dev.yml up
|
||||
```
|
||||
|
||||
### Production
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Database Models
|
||||
|
||||
### Task
|
||||
- Hierarchical structure (parent/subtasks)
|
||||
- Multiple tags per task
|
||||
- Due date and time
|
||||
- Priority and status
|
||||
- Recurrence patterns
|
||||
- Soft delete support
|
||||
|
||||
### Tag
|
||||
- Color-coded organization
|
||||
- Multi-task assignment
|
||||
- Sort ordering
|
||||
- Archive capability
|
||||
|
||||
### TimeEntry
|
||||
- Start/end timestamps
|
||||
- Duration calculation
|
||||
- User association
|
||||
|
||||
### TaskShare
|
||||
- Share tasks or entire tags
|
||||
- User-to-user sharing
|
||||
- Permission management
|
||||
|
||||
## Development
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
python manage.py test
|
||||
```
|
||||
|
||||
### Creating Migrations
|
||||
```bash
|
||||
python manage.py makemigrations
|
||||
```
|
||||
|
||||
### Collecting Static Files
|
||||
```bash
|
||||
python manage.py collectstatic
|
||||
```
|
||||
|
||||
### Code Style
|
||||
- Follow PEP 8 for Python code
|
||||
- Use meaningful variable names
|
||||
- Add docstrings to functions and classes
|
||||
|
||||
## Deployment
|
||||
|
||||
### Production Checklist
|
||||
|
||||
- [ ] Set `DEBUG = False`
|
||||
- [ ] Configure strong `SECRET_KEY`
|
||||
- [ ] Set up proper `ALLOWED_HOSTS`
|
||||
- [ ] Configure `CSRF_TRUSTED_ORIGINS` for HTTPS
|
||||
- [ ] Use PostgreSQL instead of SQLite
|
||||
- [ ] Set up Redis for Celery
|
||||
- [ ] Configure static file serving
|
||||
- [ ] Set up SSL/TLS certificates
|
||||
- [ ] Configure backup strategy
|
||||
- [ ] Set up monitoring and logging
|
||||
|
||||
### Nginx Configuration
|
||||
|
||||
Example nginx config for reverse proxy:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name tasks.firebugit.com;
|
||||
|
||||
ssl_certificate /path/to/cert.pem;
|
||||
ssl_certificate_key /path/to/key.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:8000;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
location /static/ {
|
||||
alias /path/to/static/;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Mobile App Integration
|
||||
|
||||
This server works with the KeepItGoing Android app via the sync endpoint.
|
||||
|
||||
**Sync Protocol:**
|
||||
- Client sends current state and last sync timestamp
|
||||
- Server returns updates since last sync
|
||||
- Server accepts client changes
|
||||
- Conflict resolution handled server-side
|
||||
|
||||
## Contributing
|
||||
|
||||
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
|
||||
|
||||
## License
|
||||
|
||||
Proprietary - All Rights Reserved
|
||||
Copyright (c) 2025 Firebug IT
|
||||
|
||||
## Support
|
||||
|
||||
For issues and questions:
|
||||
- Create an issue in the repository
|
||||
- Email: keith@firebugit.com
|
||||
|
||||
## Changelog
|
||||
|
||||
### Version 1.0.0 (2025-01-18)
|
||||
- Initial release
|
||||
- Complete task management system
|
||||
- Tag-based organization
|
||||
- Time tracking
|
||||
- Multi-user support
|
||||
- Mobile app sync
|
||||
- Web interface with dark mode
|
||||
- Responsive design
|
||||
- RESTful API
|
||||
|
||||
---
|
||||
|
||||
Built with ❤️ by Firebug IT
|
||||
Reference in New Issue
Block a user