InfraForge Docs

InfraNotes Project Finance · v0

Welcome

Select a document from the sidebar to read it.

InfraNotes Project Finance Microservice

Event-driven orchestration service for project-centric financial management across the InfraNotes platform

Overview

The Project Finance Microservice is an independent service that aggregates financial data from Core (expenses, invoices, budgets), Vendor (PO commitments), Asset (depreciation), and Payroll (labor costs) to provide unified project financial oversight, planning, and control.

Architecture

Frontend → Gateway → Project Finance Service
                           ↓
                    PostgreSQL (owned)
                           ↓
                    Kafka Event Bus
                      ↓         ↑
            [Consume Events] [Produce Events]
                      ↓         ↑
    Core, Vendor, Asset, Payroll, FI

Features

  • Project Financial Lifecycle Management: Track projects from planning to completion
  • Multi-Source Cost Aggregation: Aggregate costs from expenses, vendors, assets, payroll
  • Revenue Recognition: Support multiple billing models (Fixed Price, T&M, Milestone, Retainer)
  • Financial Health Scoring: Real-time health metrics and risk detection
  • Portfolio Analytics: Cross-project KPIs and forecasting
  • Vertical Integration: Foundation for Construction and IT modules

Tech Stack

  • Runtime: Go 1.25+
  • Database: PostgreSQL 15+
  • Cache: Redis 7+
  • Events: Kafka 3.x with Outbox pattern
  • Observability: DataDog APM (tracing, profiling, logs)
  • Framework: Chi router (lightweight)

Quick Start

Prerequisites

  • Go 1.25+
  • Docker & Docker Compose
  • PostgreSQL 15+
  • Redis 7+
  • Kafka 3.x (optional for local dev)

Local Development

  1. Clone the repository

    cd /home/teodorico-mazivila/Documents/InfraForge/infranotes-project-finance

  2. Install dependencies

    make deps

  3. Start infrastructure services

    docker-compose up -d postgres redis

  4. Run database migrations

    make migrate-up

  5. Run API server

    make run-api

  6. Run event consumer (in another terminal)

    make run-consumer

Docker Deployment

# Build and start all services
make docker-build
make docker-up

# API available at: http://localhost:8081

API Endpoints

Project Finance CRUD

  • POST /api/project-finance - Create project finance
  • GET /api/project-finance - List all (with filters)
  • GET /api/project-finance/id/{id} - Get single
  • PUT /api/project-finance/id/{id} - Update
  • DELETE /api/project-finance/id/{id} - Archive (soft delete)

Project Phases

  • POST /api/project-finance/{id}/phases - Create phase
  • GET /api/project-finance/{id}/phases - List phases
  • PUT /api/project-finance/{id}/phases/{phaseId} - Update phase
  • POST /api/project-finance/{id}/phases/{phaseId}/complete - Mark complete

Analytics

  • GET /api/project-finance/budget/analytics/{projectID} - Budget analytics
  • GET /api/project-finance/portfolio/analytics - Portfolio KPIs
  • GET /api/project-finance/{id}/health - Financial health score

Event Integration

Events Consumed

  • expense.created, expense.updated, expense.deleted (Core)
  • invoice.created, invoice.paid, invoice.voided (Core)
  • budget.created, budget.modified (Core)
  • po.created, po.updated (Vendor)
  • asset.cost.allocated, depreciation.run (Asset)
  • payroll.run.completed, employee.time.allocated (Payroll)
  • approval.approved, approval.rejected (Core)

Events Produced

  • project.finance.created, project.finance.updated, project.finance.archived
  • project.phase.started, project.phase.completed
  • project.milestone.reached, project.milestone.billed
  • project.budget.allocated, project.budget.exceeded
  • project.team.member.added, project.team.member.removed
  • project.financial.health.calculated, project.forecast.updated

Configuration

Configuration is loaded from environment variables. See .env.example for all options.

Required Environment Variables

# Database
DB_HOST=postgres
DB_PORT=5432
DB_NAME=project_finance
DB_USER=pf_service
DB_PASSWORD=<secret>

# Kafka
KAFKA_BROKERS=kafka:9093
KAFKA_CONSUMER_GROUP=project-finance-service
KAFKA_SASL_ENABLED=true
KAFKA_SASL_USERNAME=<secret>
KAFKA_SASL_PASSWORD=<secret>

# Auth
JWT_JWKS_URL=http://infranotes:8080/.well-known/jwks.json
JWT_AUDIENCE=infranotes-project-finance

Testing

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run linters
make lint

Development Commands

make help          # Show all available commands
make build         # Build binaries
make test          # Run tests
make lint          # Run linters
make run-api       # Run API server
make run-consumer  # Run event consumer
make clean         # Clean build artifacts

Project Structure

.
├── cmd/
│   ├── api/              # HTTP API server
│   └── consumer/         # Kafka event consumer
├── internal/
│   ├── app/              # Application initialization
│   ├── config/           # Configuration
│   ├── models/           # Domain models
│   ├── services/         # Business logic
│   ├── handlers/         # HTTP handlers
│   ├── database/         # Data access layer
│   ├── events/           # Kafka integration
│   ├── routes/           # HTTP routing
│   ├── middleware/       # HTTP middleware
│   └── utils/            # Utilities
├── migrations/           # Database migrations
├── deployments/          # Docker & K8s configs
├── docs/                 # API documentation
└── tests/                # Integration tests

Contributing

This service follows the InfraNotes Development Rules:

  • Zero Guesswork: Research before implementing
  • Production-Ready Only: No TODOs, mocks, or placeholders
  • 80%+ Test Coverage: Comprehensive tests required
  • Go 1.25+ Idioms: Modern Go patterns
  • 2025 Security Standards: OWASP 2025 compliance

License

Copyright © 2025 InfraForge. All rights reserved.

Support

For issues and questions: