Financial Analytics Module

A comprehensive financial analytics and document processing module for InfraNotes, providing advanced transaction categorization, financial insights, planning capabilities, and goal tracking.

Features

• Document Processing: Upload and process financial documents (CSV, XLSX, PDF)
• Transaction Categorization: Intelligent categorization with machine learning
• Financial Analytics: Spending analysis, trend detection, and forecasting
• Financial Planning: Budget management, planned expenses, and reminders
• Cash Flow Management: Predictions, alerts, and optimization recommendations
• Goal Tracking: Financial goal setting, progress tracking, and milestone management
• Shared JWT Authentication: Secure integration with InfraNotes core authentication via shared JWT tokens
• Performance Optimization: Redis caching and query optimization

Quick Start

Prerequisites

• Go 1.24+
• PostgreSQL 14+
• Redis 6+ (optional, for caching)

Environment Configuration

The application supports comprehensive environment configuration:

# Database Configuration
DATABASE_URL="postgres://user:password@localhost:5432/infranotes?sslmode=disable"
# OR individual components:
DB_HOST=localhost
DB_PORT=5432
DB_NAME=infranotes
DB_USER=postgres
DB_PASSWORD=your_password
DB_SSLMODE=disable

  # Redis Cache Configuration (optional)
REDIS_URL="redis://localhost:6379/0"
# OR individual components:
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

  # Authentication (shared JWT / JWKS)
  JWT_ISSUER="infranotes"
  JWT_AUDIENCE="infranotes-services"
  JWKS_URL="https://auth.infranotes.local/.well-known/jwks.json"  # preferred in production
  JWT_SECRET="your-dev-or-legacy-secret"  # only used when JWKS_URL is not set (dev/legacy)
  AUTH_SKIP=false  # must remain false outside dev/test environments

# Storage Configuration
STORAGE_TYPE=local  # or 's3' (future)
STORAGE_PATH=./storage

# S3 Configuration (when STORAGE_TYPE=s3)
S3_BUCKET=your-bucket
S3_REGION=us-west-2
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

Installation

1. Clone the repository:

git clone https://github.com/StackCatalyst/infranotes-module.git
cd infranotes-module

2. Install dependencies:

go mod download

3. Set up the database:

make migrate-up

4. Run the application:

make run

Authentication Integration

The module integrates with InfraNotes via HTTP APIs secured with shared JWT authentication:

• The InfraNotes core platform issues JWT access tokens.
• This service validates tokens locally using JWKS (JWKS_URL) or a shared HMAC secret (JWT_SECRET), with strict issuer (JWT_ISSUER) and audience (JWT_AUDIENCE) checks.
• Authentication behavior is configured via environment variables (see the "Environment Configuration" section).

For local development and automated testing, you can enable a simplified header-based development auth mode by setting AUTH_SKIP=true in a non-production environment (ENVIRONMENT=development|dev|local|test|testing).
The configuration loader rejects AUTH_SKIP=true in other environments, so this path must never be used in production.

Testing

Unit Tests

make test

Integration Tests

# Set up test environment
export INTEGRATION_TESTS=1

# Run integration tests
./scripts/run_integration_tests.sh

The integration tests cover:

• End-to-end document processing
• Authentication middleware behavior
• Database integration
• File storage operations

Test Coverage

make test-coverage

API Documentation

The module provides a comprehensive RESTful API. Key endpoints include:

• POST /api/documents - Upload financial documents
• GET /api/documents/{id}/transactions - Get extracted transactions
• GET /api/analytics/summary - Get spending summaries
• POST /api/planning/expenses - Create planned expenses
• GET /api/goals - Manage financial goals

For complete API documentation, see docs/api_documentation.md.

Architecture

High-Level Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   InfraNotes    │    │   Financial     │    │   External      │
│      Core       │◄──►│   Analytics     │◄──►│   Services      │
│                 │    │    Module       │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
    ┌────▼────┐             ┌────▼────┐             ┌────▼────┐
    │  Auth   │             │Document │             │  Redis  │
    │ Service │             │Storage  │             │ Cache   │
    └─────────┘             └─────────┘             └─────────┘

Key Components

• Document Processing: Handles file uploads and transaction extraction
• Categorization Engine: AI-powered transaction categorization
• Analytics Engine: Financial analysis and insights generation
• Planning Module: Budget and expense planning
• Goal Tracking: Financial goal management
• Cache Layer: Redis-based performance optimization

Error Handling & Resilience

The module implements comprehensive error handling and structured logging for debugging and monitoring.

Performance Features

• Redis Caching: Caches analytics results and frequently accessed data
• Query Optimization: Optimized database queries for large datasets
• Async Processing: Background document processing
• Connection Pooling: Efficient database connection management

Deployment

Docker

docker-compose up -d

Production Deployment

See docs/installation_guide.md for detailed deployment instructions.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.