Skip to content

Commit 77d61c3

Browse files
author
Gerald Kombo
committed
feat: ALBEDO initial commit — Kenya Carbon Intelligence Platform for E-Mobility
- Laravel 11 + MySQL 8 + TailwindCSS 3 + Leaflet.js + Chart.js + DOMPDF - UNFCCC AMS-III.C v16.0 with IPCC Tier 1 baseline (CO2 + CH4 + N2O) - KNCR 8-stage project lifecycle (NEMA compliance) - EPRA Guidelines 2023 charging infrastructure compliance - Carbon Markets Regulations 2024 benefit sharing (25%) - 47 counties, 8 migrations, 8 models, 4 services System Architect: Gerald Kombo
0 parents  commit 77d61c3

36 files changed

Lines changed: 1526 additions & 0 deletions

‎.env.example‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
APP_NAME=ALBEDO
2+
APP_ENV=local
3+
APP_KEY=
4+
APP_DEBUG=true
5+
APP_TIMEZONE=Africa/Nairobi
6+
APP_URL=http://localhost:8000
7+
8+
DB_CONNECTION=mysql
9+
DB_HOST=127.0.0.1
10+
DB_PORT=3306
11+
DB_DATABASE=albedo
12+
DB_USERNAME=root
13+
DB_PASSWORD=
14+
15+
MAIL_MAILER=log
16+
MAIL_FROM_ADDRESS="noreply@albedo.co.ke"
17+
MAIL_FROM_NAME="${APP_NAME}"
18+
19+
CACHE_STORE=file
20+
SESSION_DRIVER=file
21+
QUEUE_CONNECTION=sync

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
custom: ["https://albedo.co.ke/support"]

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
name: Bug Report
3+
about: Report a bug in ALBEDO
4+
title: "[BUG] "
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
## Bug Description
10+
11+
## Component Affected
12+
- [ ] `config/albedo.php`
13+
- [ ] Migration / Database schema
14+
- [ ] Model (specify which)
15+
- [ ] `CarbonCalculator` service
16+
- [ ] `LeakageCalculator` service
17+
- [ ] `AdditionalityAssessor` service
18+
- [ ] `KncrReportGenerator` service
19+
- [ ] Other: ___
20+
21+
## Steps to Reproduce
22+
1.
23+
2.
24+
3.
25+
26+
## Expected vs Actual Behavior
27+
28+
## Source Authority Impact
29+
- [ ] Yes — Specify source code: ___
30+
- [ ] No

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
name: Feature Request
3+
about: Propose a new feature for ALBEDO
4+
title: "[FEATURE] "
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
## Feature Description
10+
11+
## Problem It Solves
12+
13+
## Regulatory Alignment
14+
- [ ] IPCC 2006 Guidelines
15+
- [ ] UNFCCC AMS-III.C v16.0 / VMR0014
16+
- [ ] EPRA Guidelines 2023
17+
- [ ] Carbon Markets Regulations 2024
18+
- [ ] NEMA KNCR Process
19+
- [ ] Kenya NDC 2020
20+
- [ ] None / General improvement
21+
22+
## Priority
23+
- [ ] Critical
24+
- [ ] High
25+
- [ ] Medium
26+
- [ ] Low

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
## Description
2+
3+
## Type of Change
4+
- [ ] `feature`
5+
- [ ] `bugfix`
6+
- [ ] `refactor`
7+
- [ ] `docs`
8+
- [ ] `migration`
9+
10+
## Checklist
11+
- [ ] PSR-12 compliant
12+
- [ ] `declare(strict_types=1)` included
13+
- [ ] Tests pass (`php artisan test`)
14+
- [ ] New constants include source citation
15+
- [ ] Migration includes `down()` method
16+
- [ ] No hardcoded values
17+
18+
## Source Authority Compliance
19+
- [ ] No new constants added
20+
- [ ] New constants added with Tier ___ source: ___
21+
22+
Closes #___

‎.github/workflows/tests.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: ALBEDO CI
2+
3+
on:
4+
push:
5+
branches: [main, develop]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
tests:
11+
runs-on: ubuntu-latest
12+
services:
13+
mysql:
14+
image: mysql:8.0
15+
env:
16+
MYSQL_ROOT_PASSWORD: password
17+
MYSQL_DATABASE: albedo_test
18+
ports:
19+
- 3306:3306
20+
options: >-
21+
--health-cmd="mysqladmin ping"
22+
--health-interval=10s
23+
--health-timeout=5s
24+
--health-retries=3
25+
26+
steps:
27+
- uses: actions/checkout@v4
28+
- name: Setup PHP
29+
uses: shivammathur/setup-php@v2
30+
with:
31+
php-version: '8.2'
32+
extensions: mbstring, pdo, pdo_mysql, xml, bcmath
33+
- run: composer install --no-interaction --prefer-dist
34+
- run: cp .env.example .env && php artisan key:generate
35+
- run: |
36+
echo "DB_HOST=127.0.0.1" >> .env
37+
echo "DB_DATABASE=albedo_test" >> .env
38+
echo "DB_USERNAME=root" >> .env
39+
echo "DB_PASSWORD=password" >> .env
40+
- run: php artisan migrate --force
41+
- run: php artisan db:seed --class=CountySeeder --force
42+
- run: php artisan test

‎.gitignore‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
/node_modules
2+
/public/build
3+
/public/hot
4+
/public/storage
5+
/storage/*.key
6+
/vendor
7+
.env
8+
.env.backup
9+
.env.production
10+
.phpunit.result.cache
11+
Homestead.json
12+
Homestead.yaml
13+
auth.json
14+
npm-debug.log
15+
yarn-error.log
16+
/.fleet
17+
/.idea
18+
/.vscode
19+
20+
# ALBEDO-specific
21+
/storage/app/kncr/*.pdf
22+
/storage/app/exports/*.csv

‎CHANGELOG.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Changelog
2+
3+
Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
4+
5+
## [Unreleased] - 2026-03-16
6+
7+
### Added
8+
- Complete `config/albedo.php` with all IPCC, UNFCCC, EPRA, NEMA, KPLC constants
9+
- IPCC 2006 CH4 (33 kg/TJ) and N2O (3.2 kg/TJ) emission factors
10+
- 8 database migrations (counties through charging_stations)
11+
- MySQL GENERATED column for `net_reduction_co2e_tonnes`
12+
- 8 Eloquent models with strict type casting
13+
- `CarbonCalculator` service — IPCC Tier 1 baseline + UNFCCC project emissions
14+
- `LeakageCalculator` service — AMS-III.C deduction rules (0%, 5%, 10%)
15+
- `AdditionalityAssessor` service — Three-test evaluation
16+
- `KncrReportGenerator` service — PCN/PDD PDF generation with NDC contribution
17+
- EPRA Guidelines 2023 compliance fields
18+
- NEMA KNCR 8-stage project lifecycle tracking
19+
- Carbon Markets Regulations 2024 benefit sharing (25%)
20+
- County seeder with all 47 Kenyan counties and coordinates
21+
- KPLC E-Mobility Tariff integration (peak/off-peak)

‎CODE_OF_CONDUCT.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Code of Conduct
2+
3+
## Our Pledge
4+
5+
ALBEDO is committed to building a carbon-transparent future for Kenya's e-mobility sector. We pledge to make participation in this project a respectful, professional experience for everyone.
6+
7+
## Our Standards
8+
9+
**Expected behavior:**
10+
- Professional and respectful communication
11+
- Constructive feedback on code and methodology
12+
- Prioritizing scientific accuracy over personal opinion
13+
- Respecting regulatory compliance requirements (NEMA, EPRA, UNFCCC)
14+
- Maintaining source authority protocol
15+
16+
**Unacceptable behavior:**
17+
- Introducing unverified constants without official source citation
18+
- Bypassing the source authority protocol (Tier 1-5)
19+
- Modifying carbon calculation logic without peer review
20+
- Sharing proprietary code externally without authorization
21+
- Harassment, discrimination, or unprofessional conduct
22+
23+
## Enforcement
24+
25+
The System Architect (Gerald Kombo) will review and respond within 7 business days.
26+
27+
## Attribution
28+
29+
Adapted for ALBEDO's regulatory compliance context. Core principles from the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).

‎CONTRIBUTING.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Contributing to ALBEDO
2+
3+
Internal team collaboration guide for the ALBEDO platform.
4+
5+
## Team
6+
7+
| Role | Responsibilities |
8+
|---|---|
9+
| System Architect | Methodology design, source validation, final approval (Gerald Kombo) |
10+
11+
## Git Workflow
12+
13+
### Branch Naming
14+
```
15+
type/ticket-number-short-description
16+
```
17+
18+
Types: `feature`, `bugfix`, `hotfix`, `refactor`, `docs`
19+
20+
### Commit Messages
21+
```
22+
type: subject #ticket
23+
```
24+
25+
Examples:
26+
- `feat: add KNCR PDF generation endpoint #101`
27+
- `fix: correct leakage deduction calculation #102`
28+
29+
## Code Standards
30+
31+
1. `declare(strict_types=1)` in all PHP files
32+
2. PSR-12 compliance (4 spaces, braces on same line)
33+
3. Type hints on all parameters and return types
34+
4. Keep controllers thin — business logic in Services
35+
5. All constants in `config/albedo.php` with source citations
36+
37+
## Source Authority Protocol
38+
39+
When adding new constants:
40+
1. Identify official source (Tier 1-5)
41+
2. Verify URL accessibility
42+
3. Extract exact value (no rounding)
43+
4. Add to `config/albedo.php` with source comment
44+
5. Create PR with source documentation
45+
46+
## Database Rules
47+
48+
1. Never modify existing migrations — create new ones
49+
2. Always include `down()` method
50+
3. Use foreign keys for referential integrity
51+
4. Index frequently queried columns
52+
5. Comment complex columns
53+
54+
## Pull Request Checklist
55+
56+
- [ ] PSR-12 compliant
57+
- [ ] `declare(strict_types=1)` included
58+
- [ ] Tests pass (`php artisan test`)
59+
- [ ] New constants have source citations
60+
- [ ] Migration includes `down()` method
61+
- [ ] No hardcoded values

0 commit comments

Comments
 (0)