Teamflow

Teamflow is a modern, containerized SaaS platform for team and project management. Built with a robust backend using Django and a planned React frontend, it features role-based authentication, task tracking, and a CI/CD pipeline ready for production.

---

📋 Table of Contents

• Features
• Tech Stack
• 🚀 Getting Started
• ⚙️ Daily Development Workflow
• ✅ Code Quality & Testing
• CI/CD Pipeline
• Project Structure
• Environment Variables
• Contributing
• License

---

✨ Features

• Role-Based Authentication: Admin, Manager, and Member roles with distinct permissions.
• Project & Task Management: Create projects, assign tasks, and track their status.
• API First Design: A robust REST API built with Django REST Framework to power any frontend client.
• Dockerized Environment: Fully containerized development and production environments for consistency and ease of deployment.
• Automated Code Quality: Integrated linting and formatting with black, isort, and flake8.
• CI/CD Ready: A complete Continuous Integration pipeline using GitHub Actions to automate testing and quality checks.

---

🛠️ Tech Stack

Layer	Technology
Backend	Django, Django REST Framework
Frontend (Planned)	React
Database	PostgreSQL
Authentication	django-allauth
Development	Docker, Docker Compose
Testing	Pytest, pytest-django
CI/CD	GitHub Actions

---

🚀 Getting Started

This project is fully containerized. All you need is Git and Docker installed on your system. The Makefile abstracts away all the complexity.

Prerequisites

• Git
• Docker & Docker Compose

1. Clone the Repository

git clone https://github.com/ActualLearner/teamflow.git
cd teamflow

2. Set Up Environment Variables

Create a local environment file by copying the example. This file is ignored by Git and will hold your local secrets and configuration.

cp .env.example .env

Important: Open the .env file and review the variables. For local development, the default values are usually sufficient.

3. Build, Start, and Migrate

Run the setup command. This single command will build the Docker images, start the necessary services (web server, database), and run the initial database migrations.

make setup

Your development environment is now running!

• API Server: http://localhost:8000/
• Admin Panel: http://localhost:8000/admin/

---

⚙️ Daily Development Workflow

Use these make commands from your terminal to manage the development environment.

Command	Description
make up	🚀 Starts the Docker services in the background.
make down	🛑 Stops the Docker services.
make logs	📜 View the real-time logs from the web server.
make migrate	🏃 Run database migrations inside the container.
make shell	💻 Open an interactive shell inside the web container.
make superuser	👑 Create a new superuser for the Django admin.

---

✅ Code Quality & Testing

We enforce code quality and test coverage using a combination of tools. These checks are also run in our CI pipeline.

Command	Description
make format	🎨 Auto-formats all Python code with black and isort. Run this before committing!
make lint	🔎 Checks for code style issues and potential errors. The CI will fail if this doesn't pass.
make test	🧪 Runs the entire pytest test suite inside the container.

---

CI/CD Pipeline

This project uses GitHub Actions for Continuous Integration. The workflow is defined in .github/workflows/ci.yml and is triggered on every push or pull request to the dev, release, and main branches.

The pipeline performs the following steps:

1. Builds the Docker images.
2. Runs database migrations.
3. Performs a strict lint and format check (make lint).
4. Executes the full test suite (make test).

A merge is blocked if any of these steps fail, ensuring the main branches are always stable.

---

📁 Project Structure

teamflow/
├── .github/              # GitHub Actions workflows
├── docker/               # Docker configurations
├── src/                  # Main Django source code
│   ├── config/           # Django project settings and URLs
│   ├── users/            # Custom user model, auth logic, and APIs
│   └── manage.py
├── .env                  # Local environment variables (Git ignored)
├── .env.example          # Example environment file
├── Makefile              # All your project commands in one place
├── pyproject.toml        # Configuration for black, isort, flake8
└── requirements.txt

---

🔑 Environment Variables

The following variables need to be set in your .env file:

• SECRET_KEY: Django's secret key for cryptographic signing.
• DEBUG: Set to True for development to get detailed error pages.
• DATABASE_URL: The full connection string for PostgreSQL (e.g., postgres://user:password@db:5432/dbname).
• POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB: Used by the db service to initialize the database. These must match the credentials in DATABASE_URL.

---

🤝 Contributing

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/YourAmazingFeature.
3. Commit your changes: git commit -m "feat: Add some amazing feature".
4. Push to the branch: git push origin feature/YourAmazingFeature.
5. Open a Pull Request against the dev branch.

Please run make format before pushing to ensure code style consistency.

---

📄 License

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