Enterprise-grade German accounting standards implementation for SKR03 and SKR04
Double-entry bookkeeping with MongoDB persistence and full TypeScript support

🚀 Why @fin.cx/skr?

Building compliant German accounting software? You've come to the right place! This module provides a complete, type-safe implementation of the German standard charts of accounts (Standardkontenrahmen) SKR03 and SKR04, the backbone of professional accounting in Germany.

🎯 What makes it awesome?

🏢 Enterprise-Ready: Production-tested implementation following DATEV standards
⚡ Lightning Fast: MongoDB-powered with optimized indexing and caching
🔒 Type-Safe: Full TypeScript support with comprehensive type definitions
🎮 Developer-Friendly: Intuitive API that makes complex accounting operations simple
📈 Real-time Reporting: Generate financial statements on-the-fly
🔄 Transaction Safety: Built-in double-entry validation and reversals

📦 Installation

# Using npm
npm install @fin.cx/skr

# Using pnpm (recommended)
pnpm add @fin.cx/skr

# Using yarn
yarn add @fin.cx/skr

🎓 Quick Start

Basic Setup

import { SkrApi } from '@fin.cx/skr';

// Initialize the API
const api = new SkrApi({
  mongoDbUrl: 'mongodb://localhost:27017',
  dbName: 'accounting' // optional, defaults to 'skr_accounting'
});

// Choose your SKR standard (SKR03 or SKR04)
await api.initialize('SKR03');

💰 Posting Transactions

// Simple transaction posting
const transaction = await api.postTransaction({
  date: new Date(),
  debitAccount: '1200',  // Bank account
  creditAccount: '8400', // Revenue account  
  amount: 1190.00,
  description: 'Invoice #2024-001 payment received',
  reference: 'INV-2024-001',
  vatAmount: 190.00
});

// Complex journal entry with multiple lines
const journalEntry = await api.postJournalEntry({
  date: new Date(),
  description: 'Monthly salary payments',
  reference: 'SAL-2024-03',
  lines: [
    { accountNumber: '6000', debit: 5000.00, description: 'Gross salary' },
    { accountNumber: '4830', credit: 1000.00, description: 'Social security' },
    { accountNumber: '4840', credit: 500.00, description: 'Tax withholding' },
    { accountNumber: '1200', credit: 3500.00, description: 'Net payment' }
  ]
});

📊 Generating Reports

// Trial Balance
const trialBalance = await api.generateTrialBalance({
  dateFrom: new Date('2024-01-01'),
  dateTo: new Date('2024-12-31')
});

// Income Statement (P&L)
const incomeStatement = await api.generateIncomeStatement({
  dateFrom: new Date('2024-01-01'),
  dateTo: new Date('2024-12-31')
});

// Balance Sheet
const balanceSheet = await api.generateBalanceSheet({
  date: new Date('2024-12-31')
});

// Export for DATEV
const datevExport = await api.exportDatev({
  dateFrom: new Date('2024-01-01'),
  dateTo: new Date('2024-12-31'),
  format: 'CSV'
});

🏗️ Core Architecture

Account Management

// Create custom accounts
const account = await api.createAccount({
  accountNumber: '1299',
  accountName: 'PayPal Business',
  accountClass: 1,
  accountType: 'asset',
  description: 'PayPal business account for online payments',
  isActive: true
});

// Search accounts
const accounts = await api.searchAccounts('bank');

// Get account balance
const balance = await api.getAccountBalance('1200');
console.log(`Balance: ${balance.balance} EUR`);
console.log(`Debits: ${balance.debitTotal} EUR`);
console.log(`Credits: ${balance.creditTotal} EUR`);

Transaction Management

// Get transaction history
const transactions = await api.listTransactions({
  accountNumber: '1200',
  dateFrom: new Date('2024-01-01'),
  dateTo: new Date('2024-12-31'),
  minAmount: 100,
  maxAmount: 10000
});

// Reverse a transaction
const reversal = await api.reverseTransaction(transactionId);

// Batch processing
const batchResults = await api.postBatchTransactions([
  { date: new Date(), debitAccount: '1200', creditAccount: '8400', amount: 100 },
  { date: new Date(), debitAccount: '1200', creditAccount: '8400', amount: 200 },
  { date: new Date(), debitAccount: '1200', creditAccount: '8400', amount: 300 }
]);

📚 SKR03 vs SKR04: Which One to Choose?

SKR03 - Process Structure Principle (Prozessgliederungsprinzip)

Best for: 🛍️ Trading companies, 💼 Service providers, 🏪 Retail businesses

Accounts organized by business process flow
Easier mapping to operational workflows
Natural progression from purchasing → inventory → sales
Popular with small to medium enterprises

SKR04 - Financial Classification Principle (Abschlussgliederungsprinzip)

Best for: 🏭 Manufacturing companies, 🏗️ Large corporations, 📈 Public companies

Accounts organized by financial statement structure
Direct mapping to balance sheet and P&L positions
Simplified financial reporting and analysis
Preferred by auditors and financial institutions

🎯 Account Structure

Both SKR standards follow the same hierarchical structure:

[0-9]    → Account Class (Kontenklasse)
 [0-9]   → Account Group (Kontengruppe)
  [0-9]  → Account Subgroup (Kontenuntergruppe)
   [0-9] → Individual Account (Einzelkonto)

Account Classes Overview

Class	SKR03 Description	SKR04 Description	Type
0	Fixed Assets	Fixed Assets	Asset
1	Current Assets	Current Assets	Asset
2	Equity	Equity	Equity
3	Liabilities	Liabilities	Liability
4	Operating Income	Operating Income	Revenue
5	Cost of Materials	Cost of Materials	Expense
6	Operating Expenses	Other Operating Costs	Expense
7	Other Income/Expenses	Other Income/Expenses	Mixed
8	---	Financial Results	Mixed
9	Closing Accounts	Closing Accounts	System

🔧 Advanced Features

Ledger Operations

import { Ledger } from '@fin.cx/skr';

const ledger = new Ledger('SKR03');

// Post to general ledger
await ledger.postToGeneralLedger(transaction);

// Get account ledger
const accountLedger = await ledger.getAccountLedger('1200', {
  dateFrom: new Date('2024-01-01'),
  dateTo: new Date('2024-12-31')
});

// Close accounting period
await ledger.closePeriod('2024-01');

Custom Reporting

import { Reports } from '@fin.cx/skr';

const reports = new Reports('SKR03');

// Generate custom report
const customReport = await reports.generateCustomReport({
  accounts: ['1200', '1300', '1400'],
  dateFrom: new Date('2024-01-01'),
  dateTo: new Date('2024-12-31'),
  groupBy: 'month',
  includeSubAccounts: true
});

// Cash flow statement
const cashFlow = await reports.generateCashFlowStatement({
  year: 2024
});

Data Import/Export

// Import from CSV
const importedCount = await api.importAccountsFromCSV(csvContent);

// Export to CSV
const csvExport = await api.exportAccountsToCSV();

// DATEV-compatible export
const datevData = await api.exportDatev({
  consultantNumber: '12345',
  clientNumber: '67890',
  dateFrom: new Date('2024-01-01'),
  dateTo: new Date('2024-12-31')
});

🛡️ Type Safety

Full TypeScript support with comprehensive type definitions:

import type { 
  TSKRType,
  IAccountData,
  ITransactionData,
  IJournalEntry,
  ITrialBalanceReport,
  IIncomeStatement,
  IBalanceSheet
} from '@fin.cx/skr';

// All operations are fully typed
const account: IAccountData = {
  accountNumber: '1200',
  accountName: 'Bank Account',
  accountClass: 1,
  accountType: 'asset',
  skrType: 'SKR03',
  vatRate: 0,
  isActive: true
};

🌟 Real-World Example

Here's a complete example of setting up a basic accounting system:

import { SkrApi } from '@fin.cx/skr';

async function setupAccounting() {
  // Initialize
  const api = new SkrApi({
    mongoDbUrl: process.env.MONGODB_URL!,
    dbName: 'my_company_accounting'
  });
  
  await api.initialize('SKR03');
  
  // Create custom accounts for your business
  await api.createAccount({
    accountNumber: '1299',
    accountName: 'Stripe Account',
    accountClass: 1,
    accountType: 'asset',
    description: 'Stripe payment gateway account'
  });
  
  // Post daily transactions
  const transactions = [
    { 
      date: new Date(),
      debitAccount: '1299', // Stripe
      creditAccount: '8400', // Revenue
      amount: 99.00,
      description: 'SaaS subscription payment',
      reference: 'stripe_pi_abc123'
    },
    {
      date: new Date(),
      debitAccount: '5900', // Hosting costs
      creditAccount: '1200', // Bank
      amount: 29.99,
      description: 'AWS monthly bill',
      reference: 'aws-2024-03'
    }
  ];
  
  for (const tx of transactions) {
    await api.postTransaction(tx);
  }
  
  // Generate monthly report
  const report = await api.generateIncomeStatement({
    dateFrom: new Date('2024-03-01'),
    dateTo: new Date('2024-03-31')
  });
  
  console.log('Revenue:', report.totalRevenue);
  console.log('Expenses:', report.totalExpenses);
  console.log('Net Income:', report.netIncome);
  
  // Close the connection when done
  await api.close();
}

setupAccounting().catch(console.error);

🚦 API Reference

Main Classes

SkrApi - Main API entry point
ChartOfAccounts - Account management
Ledger - General ledger operations
Reports - Financial reporting
Account - Account model
Transaction - Transaction model
JournalEntry - Journal entry model

Key Methods

Method	Description
`initialize(skrType)`	Initialize with SKR03 or SKR04
`postTransaction(data)`	Post a simple transaction
`postJournalEntry(data)`	Post a complex journal entry
`reverseTransaction(id)`	Reverse a posted transaction
`generateTrialBalance(params)`	Generate trial balance report
`generateIncomeStatement(params)`	Generate P&L statement
`generateBalanceSheet(params)`	Generate balance sheet
`exportDatev(params)`	Export DATEV-compatible data

📋 Requirements

Node.js >= 18.0.0
MongoDB >= 5.0
TypeScript >= 5.0 (for development)

🏆 Why Developers Love It

🎯 Zero Configuration: Pre-configured SKR03/SKR04 accounts out of the box
🔄 Automatic Validation: Never worry about unbalanced entries
📊 Real-time Analytics: Instant financial insights
🛡️ Production Ready: Battle-tested in enterprise environments
📚 Great Documentation: You're reading it!
🤝 Active Community: Regular updates and support

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

readme.md

@fin.cx/skr 📊