Skip to content

README.md

Latest commit

 

History

History
218 lines (164 loc) · 6.4 KB

README.md

File metadata and controls

218 lines (164 loc) · 6.4 KB
Raw

Requirements Tracker

A Flask-based requirements management system with Gherkin syntax support, version control, and activity logging.

License: GPL v3 Python Flask

📸 Screenshots

Dashboard Overview

Dashboard Main dashboard showing project overview and recent activities

Project Management

Projects Project listing and management interface

Creating New Requirements

New Requirement Interface for creating new requirements with Gherkin syntax support

Analytics and Reporting

Analytics Analytics dashboard with requirement statistics and trends

Administrative Panel

Admin Panel Administrative interface for user and system management

✨ Features

  • Gherkin Requirements: Write requirements in standard Gherkin syntax
  • Version Control: Track changes to requirements with full history
  • Project Management: Organize requirements by projects
  • Activity Logging: Track all user actions and changes
  • Search Functionality: Full-text search using Whoosh
  • User Management: Role-based access control
  • Traceability: Link requirements to each other
  • Modern UI: Bootstrap-based interface matching TimeTracker
  • Analytics: Comprehensive reporting and statistics

🚀 Quick Start

Option 1: Local Development (Recommended)

  1. Clone the repository:

    git clone https://github.com/DRYTRIX/RequirementsTracker.git
cd RequirementsTracker

  2. Install dependencies:

    pip install -r requirements-minimal.txt

  3. Initialize the database:

    flask init-db

  4. Create an admin user:

    flask create-admin

  5. Start the development server:

    python run.py

  6. Access the application at http://localhost:5000

Option 2: Docker Deployment

With PostgreSQL (Production)

docker-compose up --build

With SQLite (Simple)

docker build -t requirementstracker .
docker run -p 8080:8080 -v $(pwd)/data:/data requirementstracker

Option 3: Windows Deployment Script

deploy.bat

🛠️ CLI Commands

  • flask init-db - Initialize the database
  • flask create-admin - Create an admin user
  • flask create-user - Create a new user
  • flask create-project - Create a new project
  • flask list-users - List all users
  • flask list-projects - List all projects
  • flask stats - Show application statistics

⚙️ Configuration

The application uses environment variables for configuration:

  • SECRET_KEY - Flask secret key (default: auto-generated)
  • DATABASE_URL - Database connection string (default: SQLite)
  • ALLOW_SELF_REGISTER - Allow automatic user creation (default: true)
  • ADMIN_USERNAMES - Comma-separated list of admin usernames

🗄️ Database

The application supports both SQLite (default) and PostgreSQL:

  • SQLite: Perfect for development and small deployments
  • PostgreSQL: Recommended for production with multiple users

📁 Project Structure

RequirementsTracker/
├── app/
│   ├── models/          # Database models
│   ├── routes/          # Flask routes
│   ├── templates/       # Jinja2 templates
│   ├── static/          # Static files (CSS, JS, images)
│   └── utils/           # Utility functions
├── assets/
│   └── screenshots/     # Application screenshots
├── data/                # Application data (uploads, search index)
├── logs/                # Application logs
├── tests/               # Test files
├── app.py              # Main application entry point
├── run.py              # Development server runner
├── requirements.txt    # Full dependencies
├── requirements-minimal.txt  # Minimal dependencies
├── docker-compose.yml  # Docker Compose configuration
├── Dockerfile          # Docker configuration
└── deploy.bat          # Windows deployment script

🔌 API Endpoints

  • GET / - Dashboard
  • GET /health - Health check
  • GET /projects - List projects
  • GET /projects/<id> - View project
  • GET /requirements - List requirements
  • GET /requirements/<id> - View requirement
  • GET /search - Search requirements
  • GET /profile - User profile
  • GET /about - About page
  • GET /help - Help documentation

🧪 Development

Running Tests

python -m pytest tests/

Code Formatting

black app/ tests/

Linting

flake8 app/ tests/

🔧 Troubleshooting

Common Issues

  1. "Failed to find attribute 'app' in 'app'"

    • This is fixed in the current version. The Dockerfile now uses app:create_app()

  2. Database connection errors

    • For SQLite: Ensure the data/ directory exists and is writable
    • For PostgreSQL: Check connection string and database availability

  3. Import errors

    • Install dependencies: pip install -r requirements-minimal.txt
    • For full features: pip install -r requirements.txt

  4. Permission errors (Docker)

    • The Docker container runs as non-root user (appuser)
    • Ensure data directories have correct permissions

Logs

  • Local development: Check console output
  • Docker: docker-compose logs -f
  • Application logs: Check logs/ directory

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

🤝 Contributing

  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

📞 Support

For issues and questions, please contact the development team or open an issue on GitHub.

🔗 Links