Welcome to Fiscal, a robust platform engineered for the precise calculation, management, and reporting of tax levies. This repository contains the core services that ensure the accuracy and audibility of all financial transactions related to tax obligations.
At the heart of our architecture lies a powerful combination of Command Query Responsibility Segregation (CQRS) and Event Sourcing. This strategic choice empowers us to:
- Ensure Data Integrity: By separating command (write) and query (read) models, and by persisting every change as an immutable event, we maintain a highly consistent, verifiable, and auditable state for complex tax rules and financial records.
- Optimize for Complex Calculations: Commands can be specifically designed for the intricate logic required for tax assessments, while Event Sourcing provides a precise historical record of all calculation inputs and outcomes.
- Enhance Performance for Auditing & Reporting: Our read models, stored in MongoDB, are optimized for rapid data retrieval, crucial for generating comprehensive tax reports and enabling quick audits.
For a deeper understanding of our architectural approach, please refer to the Architecture section below.
- Accurate Tax Levy Calculations: Core engine designed for high precision in complex tax rule application.
- Immutable Transaction History: Complete audit trail of all financial events related to tax obligation.
- Optimized Reporting: Fast and flexible generation of various tax-related reports and dashboards from MongoDB read models.
- Scalable Architecture: Designed to handle increasing volumes of financial data and tax rules.
- Robust Functionalities designed to meet your business needs, including:
- Seamless Integration with external Tax APIs: Easily connect to external tax calculations services for real-time tax assessment and compliance.
- Comprehensive User Management for Taxpayers, ensuring secure and personalized experiences.
This project is fundamentally designed around the Command Query Responsibility Segregation (CQRS) pattern, significantly enhanced by Event Sourcing. This powerful combination is critical for the Fiscal app, enabling us to manage complex tax calculations, ensure unparalleled data integrity, and provide a complete, verifiable audit trail for every financial transaction and levy assessment.
- CQRS: At its core, CQRS separates the responsibility of handling commands (data modification) from queries (data retrieval).
- The Command side (writes) is primarily managed by the Spring Boot application, processing business logic and persisting events.
- The Query side (reads) leverages MongoDB to store denormalized read models, which are efficiently accessed by client applications using GraphQL.
- Event Sourcing: Instead of just storing the current state, we persist every change as an immutable sequence of domain events. This provides a complete, granular, and auditable history of all financial activities, which is paramount for regulatory compliance and forensic analysis in the tax domain. Events are then used to update the read models in MongoDB and potentially graph relationships in Neo4j.
For a comprehensive understanding of these architectural patterns and our approach, we highly recommend the following resources:
- Bob Reselman's Red Hat, Inc. an illustrated guide to CQRS data patterns: A foundational resource covering the intricacies of CQRS in depth. https://redhat.com/en/blog/illustrated-cqrs
- Martin Fowler's Event Sourcing article: An excellent seminal piece providing a clear explanation of Event Sourcing Fundamentals. https://martinfowler.com/eaaDev/EventSourcing.html
We also adhere to principles of Domain-Driven Design (DDD) to ensure our models accurately reflect the complexities of tax law and financial regulations, fostering a shared understanding between domain experts and developers.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
Ensure you have the following installed and configured:
- Java Development Kit (JDK): Versions 17 or higher (e.g., OpenJDK).
- Maven: Version 3.x.x (for building the Spring Boot application).
- Neo4j Database: A running instance of Neo4j (Community Edition is sufficient).
- You can run it locally, or via Docker:
docker run --name neo4j -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/password -d neo4j
- You can run it locally, or via Docker:
- MongoDB Database: A running instance of MongoDB.
- You can run it locally, or via Docker:
docker run --name mongodb -p 27017:27017 -d mongo
- You can run it locally, or via Docker:
- Git: For cloning the repository.
- Optional: A GraphQL client library or tool within your client application for querying MongoDB.
This project is licensed under the MIT License - see the License file for details.