file-explorer-api-r2/README.md

# Cloudflare Worker API Template

A production-ready template for building secure, modular APIs with Cloudflare Workers, featuring built-in authentication, database integration, and comprehensive documentation.

## Features

- **Authentication & Authorization**: Pre-configured with API key and Bearer token authentication
- **Database Integration**: Ready-to-use D1 database connections
- **Storage**: R2 bucket integration for file storage
- **Documentation**: Auto-generated Swagger/OpenAPI documentation
- **CI/CD**: GitHub Actions workflows for automated deployments
- **Environment Management**: Development, Playtest, and Production environments

## Design Documentation

All design documentation should be maintained in the blueprint repository:

1. Create design documentation in the blueprint repository located at `<app_name_lower_case>`
2. Submit the design as a Pull Request to the blueprint repository
3. Once approved, add the link to the design file in `docs/DESIGN.md`

The `docs/DESIGN.md` file should contain a reference to the design document's location in the blueprint repository.

## Getting Started

### Using This Template

1. **Checkout the template branch**:
   ```bash
   git clone <repository-url>
   git checkout template
   ```

2. **Replace placeholder variables**:
   Search and replace the following placeholders throughout the codebase:
   - `<app_name_lower_case>` - Your application name in lowercase (e.g., `my-api`)
   - `<app_name_upper_case>` - Your application name in uppercase (e.g., `MY_API`)
   
   Make sure to check all files, especially:
   - `wrangler.toml`
   - `.github/workflows/deploy.yaml`
   - `src/swagger/config.js`

3. **Set up a new Git repository**:
   ```bash
   # Remove existing Git history
   rm -rf .git
   
   # Initialize a new Git repository
   git init
   
   # Add your remote repository
   git remote add origin <your-new-repository-url>
   
   # Add all files
   git add .
   
   # Commit
   git commit -m "Initial commit from template"
   
   # Push to main branch
   git push -u origin main
   ```

4. **Create development branches**:
   ```bash
   # Create and push dev branch
   git checkout -b dev
   git push -u origin dev
   
   # Create and push playtest branch
   git checkout -b playtest
   git push -u origin playtest
   ```

## Branching Strategy

Follow this workflow for code changes:

1. **Feature Development**:
   - Create feature branches from `dev`
   - Name format: `feature/your-feature-name`

2. **Deployment Flow**:
   - **Playtest**: Merge directly from feature branches for testing
   - **Development**: Submit Pull Requests from feature branches
   - **Production**: Submit Pull Requests from `dev` to `main`

## Configuration

### Database (D1)

The template comes with D1 database configuration. If you need to use it:

1. Create your D1 databases for each environment:
   ```bash
   create <app_name_lower_case>_dev
   create <app_name_lower_case>_playtest
   create <app_name_lower_case>_prod
   ```

2. Update the database IDs in `wrangler.toml` with the IDs generated from the commands above.

If you don't need D1, remove the `d1_databases` sections from `wrangler.toml`.

### Storage (R2)

The template includes R2 bucket configuration. If you need to use it:

1. Create your R2 buckets for each environment:
   ```bash
   create <app_name_lower_case>-dev
   create <app_name_lower_case>-playtest
   create <app_name_lower_case>-prod
   ```

2. Update the bucket names in `wrangler.toml`.

If you don't need R2, remove the `r2_buckets` sections from `wrangler.toml`.

## Authentication

The API comes with two authentication methods:

1. **API Key Authentication**: Using the `X-Api-Key` header
2. **Bearer Token Authentication**: Using the `Authorization: Bearer <token>` header

These are configured in the Swagger documentation and middleware. Do not modify the authentication mechanisms unless necessary.

## API Documentation

The API documentation is generated using Swagger/OpenAPI. The configuration is modular and located in:

- `src/swagger/config.js`: Main configuration
- `src/swagger/endpoints/`: Individual endpoint definitions

When adding new endpoints:

1. Create a new file in `src/swagger/endpoints/` for your endpoint
2. Export the endpoint configuration
3. Import and add it to `src/swagger/config.js`

Access the documentation at `/api/<app_name_lower_case>/docs` when the API is running.

## Design Documentation

All design documentation should be maintained in the blueprint repository:

1. Create design documentation in the blueprint repository located at `<app_name_lower_case>`
2. Submit the design as a Pull Request to the blueprint repository
3. Once approved, add the link to the design file in `docs/DESIGN.md`

The `docs/DESIGN.md` file should contain a reference to the design document's location in the blueprint repository.

## Code Structure Guidelines

- Keep files modular and under 100 lines
- Organize related functionality into separate modules
- Place shared logic in `src/helpers/` or appropriate service directories
- Follow the existing pattern for new endpoints and services

## Development

### Local Development

This project uses Docker for local development to ensure consistency across environments:

```bash
# Start the local development server
docker compose up

# To run in detached mode
docker compose up -d

# To stop the server
docker compose down
```

The server will be available at http://localhost:8787.

### Deployment

Deployments are handled automatically by GitHub Actions when pushing to the appropriate branches:

- Push to `playtest` → Deploys to Playtest environment
- Push to `dev` → Deploys to Development environment
- Push to `main` → Deploys to Production environment

## License

[MIT](LICENSE)

## Development Checklist

Follow this checklist when working on a new feature or issue:

- [ ] Define Issue with Acceptance Criteria - Issue ID
- [ ] Create one or more Tasks to Work on Issue Task ID
- [ ] Create/Update Design Documentation - Design DOcument Link
- [ ] Create PR for Design Documentation - PR ID
- [ ] Follow Steps in README to create your own project Repository ID
- [ ] Commit Code and test default code in all 3 environments - PlayTest Url
- [ ] Create feature branch for your issue - <Branch Name>
- [ ] Write your own code  Method Id /Url
- [ ] Test locally using docker compose 
- [ ] Merge to playtest branch 
- [ ] Test on Cloudflare 
- [ ] Request PR to dev branch PR ID