Get in Touch

Project Case Study: Financial & Legal Case Manager

Live Demo: https://app.komocred.com.br
Public Repository: github.com/VanFalchi/financial-legal-manager

1. The Challenge: From Spreadsheet Chaos to a Single Source of Truth

The Business Problem: The project began with a client, a specialized financial-legal firm, trapped in a high-risk, inefficient workflow. Their entire operation—managing sensitive client data, tracking legal cases, and calculating complex, multi-party financial distributions—was run on manual spreadsheets. This process was not only labor-intensive but also dangerously prone to human error, posing significant financial and compliance risks.

The Mission: To design and build a secure, centralized, and intuitive 3-tier web application that would serve as the single source of truth for the firm. The primary goal was to eliminate manual data entry, automate all financial calculations, and provide a resilient, production-ready system for a team of non-technical users.

 

2. My Role: End-to-End Ownership

As the sole developer and DevOps engineer on this project, I was responsible for the entire software development lifecycle. This encompassed:

  • Product Management: Conducting the initial client briefing, translating business needs into technical requirements, and defining the MVP scope.

  • Software Architecture: Designing a robust, secure, and maintainable 3-tier architecture from the ground up.

  • Full-Stack Development: Building the Python/Flask backend, modeling the PostgreSQL database with SQLAlchemy, and crafting a clean, server-rendered frontend with Jinja2 and Tailwind CSS.

  • DevOps & Infrastructure: Containerizing the entire stack with Docker, configuring a production-ready environment on a Linux VPS with Nginx and Gunicorn, and building a fully automated CI/CD pipeline with GitHub Actions.

  • Quality Assurance: Performing end-to-end testing, debugging, and iteratively refining the application based on real-world use cases.

 

3. The Technical Deep Dive: Building a Resilient System

This project was an exercise in applying DevOps principles to create a system that is not just functional, but also secure, automated, and resilient.

3.1. System Architecture

The application is built on a classic, robust 3-tier architecture, fully containerized with Docker for perfect parity between development and production.

3.2. Technical Highlights & Challenges Overcome
 
Highlight 1: The Secure, “Zero-Trust” CI/CD Pipeline

A key requirement was a fully automated deployment pipeline that was also completely secure. A standard CI/CD setup would require opening the server’s SSH port to the world, which was unacceptable.

  • The Challenge: How to allow GitHub Actions to deploy to a server whose SSH port is locked down and only accessible via a private VPN (Tailscale)?
  • The Solution: I implemented a self-hosted runner directly on the VPS. This agent polls GitHub for jobs, eliminating the need for any inbound connections from the outside. The CI/CD workflow was simplified to a secure, internal process.
  • Troubleshooting in Action: The implementation faced multiple real-world challenges, including Docker permission errors (EACCES: permission denied) and environment variable scope issues. These were solved by adding a workspace cleanup step with sudo chown to the workflow and by securely creating the .env file from a GitHub Secret at the beginning of each run. This process transformed a fragile pipeline into a resilient, self-correcting automation.
 
Highlight 2: Proactive Disaster Recovery & Resilience

The client’s hosting plan did not include automated backups, posing a significant business risk.

  • The Challenge: How to create a reliable, automated backup system without incurring extra costs?
  • The Solution: I leveraged the hosting provider’s API and the Linux cron scheduler. I wrote a bash script that uses the cntb CLI tool to:
    1. Create a new server snapshot.
    2. List all existing snapshots.
    3. If the number of snapshots exceeds the free limit (2), it automatically deletes the oldest one. This script was then scheduled with cron to run twice a week, creating a robust, cost-free, and automated backup rotation system.
 
Highlight 3: Intelligent UI to Prevent User Error

The end-users are non-technical, making it crucial to design an interface that actively prevents mistakes.

  • The Challenge: The type of financial transactions allowed depends entirely on the type of legal case. A user could easily select an invalid combination, leading to incorrect calculations.
  • The Solution: I used conditional logic within the Jinja2 templates to dynamically render the transaction form. Based on the case_type variable passed from the Flask backend, the HTML dropdown menu disables invalid options, making it impossible for the user to select a wrong combination. This simple server-side check significantly improves data integrity and the user experience.

4. Lessons Learned & Future Steps

  • The Power of a Real-World Crucible: This project was a powerful lesson in the difference between theory and practice. The biggest challenges—and the most valuable learning experiences—came from debugging real-world deployment issues related to network configuration, file permissions, and the subtle interactions between Docker, Nginx, and the CI/CD agent.

  • What I Would Do Differently: If starting today, I would integrate an automated testing suite with pytest from day one. While manual QA was effective for the MVP, a robust test suite would provide an even stronger safety net, especially for the critical calculos.py module, allowing for faster and more confident iterations in the future.

  • Next Steps (The “Season 2”): The current MVP is a solid foundation. Future enhancements planned include integrating a dedicated object storage service (like Backblaze B2 or DO Spaces) for document uploads and implementing a full observability stack with Prometheus and Grafana to monitor the application’s health and performance in real-time.