@blue-impact-engine/blue-impact-engine-client/README.md

Blue Impact Engine API Client

# Blue Impact Engine

A full-stack application for managing impact projects with a Next.js frontend and Payload CMS backend.

## Quick Start

### Option 1: Clean Startup (Recommended)

```bash
start-clean.bat
```

### Option 2: PowerShell Script

```powershell
powershell -ExecutionPolicy Bypass -File "start.ps1"
```

### Option 3: Manual Startup

1. **Start Backend** (Port 3001):

   ```bash
   cd ../blue-impact-api
   npx next dev --port 3001
   ```

2. **Start Frontend** (Port 3000):

   ```bash
   npx next dev --port 3000
   ```

## Access Points

- **Frontend (UI)**: http://localhost:3000
- **Backend Admin**: http://localhost:3001/admin
- **Backend API**: http://localhost:3001/api

## Features

- **Project Management**: View and manage impact projects
- **User Management**: Admin user interface
- **Media Management**: File uploads and management
- **Organization Management**: Multi-tenant support
- **Tag System**: Categorization and organization

## Architecture

- **Frontend**: Next.js 15 with TypeScript and Bootstrap 5
- **Backend**: Payload CMS with MongoDB
- **API**: RESTful endpoints for all collections
- **Database**: MongoDB with sample data

## Project component design

### Component responsibilities

Describe responsibilities of this component.

### Component interface

Define all types that this component should expose.

### Sequence diagram

```mermaid
sequenceDiagram
    participant ReactFrontend
    participant BlueImpactClient
    participant ProjectService
    participant HttpClient
    participant RemoteAPI

    ReactFrontend->>BlueImpactClient: getProjectService()
    BlueImpactClient-->>ReactFrontend: ProjectService

    ReactFrontend->>ProjectService: findFeaturedProjects()
    ProjectService->>HttpClient: callApi()
    HttpClient->>RemoteAPI: HTTP request
    RemoteAPI-->>HttpClient: HTTP response (JSON)
    HttpClient-->>ProjectService: ApiResponse
    ProjectService->>ProjectService: createProjectList()
    create participant Project
    ProjectService->>Project: Project()
    Project-->>ProjectService: project
    ProjectService-->>BlueImpactClient: Array<Project>
    BlueImpactClient-->>ReactFrontend: Array<Project>
```

## Development

The application uses:

* Next.js App Router
* Server and Client Components
* TypeScript for type safety
* Bootstrap 5 for styling
* Payload CMS for content management

## Data Flow

1. Frontend (Port 3000) serves the UI
2. Backend (Port 3001) provides API endpoints
3. All data entry happens through the frontend admin interface
4. Backend acts as a pure API layer

## Stopping the Application

Press `Ctrl+C` in the terminal where the servers are running, or run:

```powershell
Get-Job | Stop-Job
Get-Job | Remove-Job
``` 

# Publishing the package

For the Blue Impact Engine, an organisation is created at npmjs to publish the packages to that scope.

To publish this repository as an NPM package, do the following:

1. Login to [npmjs.com](https://www.npmjs.com/) with `npm login --scope=@blue-impact-engine`
1. Publish the package as a public package: `npm publish --access public`
1. When publishing a pre-release version, run `npm publish --access public --tag "latest"`

## About versioning

NPM requires packages to use [symentic versioning](https://semver.org/). This means versions have the following structure: `MAJOR.MINOR.PATCH`.

For the Blue Impact Engine Client we also use the following labels for pre-build releases:

* `-alhpa` for a release that is still under heavy development and is changing constantly.
* `-beta` for a release that is working towards a stable version but is not completely tested yet. It still may contain bugs and breaking changes.