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)

start-clean.bat

Option 2: PowerShell Script

powershell -ExecutionPolicy Bypass -File "start.ps1"

Option 3: Manual Startup

1. Start Backend (Port 3001):

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

2. Start Frontend (Port 3000):

   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

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:

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 with npm login --scope=@blue-impact-engine
2. Publish the package as a public package: npm publish --access public
3. When publishing a pre-release version, run npm publish --access public --tag "latest"

About versioning

NPM requires packages to use symentic versioning. 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.