# Project Ploughshares

[![Build Status](https://woodpecker.nixc.us/api/badges/colin/ploughshares/status.svg)](https://woodpecker.nixc.us/colin/ploughshares)

A transaction management system.

Current version: 0.1.2

## Development

### Local Development

For local development, use the development Docker Compose configuration:

```bash
docker-compose -f docker-compose.dev.yml up --build
```

This will:
- Mount the source code as a volume for live reloading
- Enable Flask debug mode
- Expose the PostgreSQL port for direct access

### Production

For production deployment, use the production stack configuration:

```bash
docker stack deploy -c stack.production.yml ploughshares
```

### Staging

For staging deployment, use the staging stack configuration:

```bash
docker stack deploy -c stack.staging.yml ploughshares-staging
```

## CI/CD

This project uses Woodpecker CI for continuous integration and deployment. The pipeline:

1. Builds the Docker image for multiple architectures
2. Pushes the image to the registry
3. Deploys to the production environment

## Configuration Files

- `docker-compose.yml` - Default configuration for quick setup
- `docker-compose.dev.yml` - Development configuration with live reloading
- `stack.production.yml` - Production deployment with Docker Swarm
- `stack.staging.yml` - Staging deployment with Docker Swarm
- `.woodpecker.yml` - CI/CD pipeline configuration

## Database

The application uses PostgreSQL for data storage. The database schema is automatically initialized using the `schema.sql` file.

## API

The application provides a RESTful API for managing transactions. See the API documentation at `/api-docs` when the application is running.

## Version Management

The application uses semantic versioning (X.Y.Z) with the following components:

- The `VERSION` file at the root of the repository is the single source of truth for the application version
- The web UI and application automatically read the version from this file
- Version changes are managed using the `versionbump.sh` script
- A version history log is maintained in `version_history.log`

### Version Bump Script

The `versionbump.sh` script provides the following commands:

```bash
# To bump the patch version (e.g., 1.0.0 -> 1.0.1)
./versionbump.sh patch

# To bump the minor version (e.g., 1.0.0 -> 1.1.0)
./versionbump.sh minor

# To bump the major version (e.g., 1.0.0 -> 2.0.0)
./versionbump.sh major

# To set a specific version
./versionbump.sh set X.Y.Z

# To show help information
./versionbump.sh --help
```

### Version Consistency

The version is maintained in:
- `VERSION` file (source of truth)
- Docker Compose environment variables (APP_VERSION)

The application reads the version from:
1. The APP_VERSION environment variable if set
2. The VERSION file in the current directory
3. The VERSION file at the root of the repository

## Code Quality and Security

**IMPORTANT**: Code quality and security tools are **REQUIRED** for this project.

Install the necessary tools with:

```bash
./install-codechecks.sh
```

This installs:
- flake8: Code style checker
- safety: Dependency vulnerability scanner
- bandit: Security issue scanner
- pytest: Testing framework

### Running Tests

The project includes tests for:
- Core application functionality
- Code quality standards
- Dependency vulnerability checking

Run tests with:

```bash
python3 -m pytest tests/
```

## Docker Setup

The application is containerized using Docker and can be run using docker-compose.

```bash
# Build the containers
docker-compose build

# Start the application
docker-compose up
```

The application will be available at http://localhost:5001.

## Features

- Transaction management (create, view, edit)
- Document uploads and attachments
- API endpoints for programmatic access
- PostgreSQL database for data storage

## Running the Application

### Using Docker (Recommended)

The application can be run using Docker:

```bash
# Run with PostgreSQL database
docker-compose up --build
```

This will:
1. Build the Docker image
2. Start PostgreSQL database
3. Initialize the database schema
4. Start the application on port 5001

#### Stopping the Application

```bash
# Stop all containers
docker-compose down
```

## API Documentation

API documentation is available at:
- http://localhost:5001/api-docs

## Accessing the Application

The application runs on all addresses (0.0.0.0) and is accessible via:
- http://localhost:5001 (Docker)
- http://localhost:5001 (Local)
- http://<machine-ip>:5001 (Network access)