Skip to content

Chapter 1: Project Vision and Objectives

1.1. Introduction: The Problem

Modern investment portfolio management, while accessible, presents growing complexity. Active investors interact with multiple platforms: brokers for transactions, analysis services for research (e.g., TipRanks), and market data sources for price tracking (e.g., Marketstack).

This fragmentation creates a significant manual workload and makes it difficult to obtain a unified, accurate, and historical overview of portfolio performance. Answering simple questions like "What was the real performance of my stock X, all currencies included?" or "Which assets are outperforming today?" requires tedious and error-prone consolidation.

1.2. The Solution: The "Augmented Financial Analyst" Project

The "Augmented Financial Analyst" project was designed to solve this problem by providing a private, centralized, and automated portfolio analysis platform.

The application acts as a personal hub that:

  1. Consolidates the portfolio composition from a single, controlled data source.
  2. Automatically enriches this data with the previous day's closing prices.
  3. Analyzes the evolution and performance of the portfolio, both globally and for each individual stock.
  4. Presents this information clearly and visually through a private and secure web interface.

The ultimate goal is to transform raw, scattered data into actionable information, allowing the user to make more informed investment decisions and track their asset performance with absolute confidence.

1.3. Key Objectives

The project's objectives are divided into two categories: functional objectives (what the application does) and non-functional objectives (the quality principles that govern its operation).

1.3.1. Functional Objectives

  • Portfolio Import: The application must be able to import and synchronize the complete portfolio composition (list of stocks, quantities) from a CSV configuration file.
  • Automated Data Enrichment: The system must, autonomously and daily, retrieve the previous day's (D-1) closing prices for each stock via an external financial API (Marketstack).
  • Data Historization: Each daily price record must be stored persistently, creating a complete history to track the value evolution of each stock and the overall portfolio over time.
  • Secure Access: Access to all data and analysis must be protected and strictly limited to a single authenticated user via a login system.
  • Visual Presentation:
    • A global dashboard must present an overview of the portfolio, including its total value, daily performance, and evolution charts.
    • Detail pages must allow for in-depth analysis of each stock, including a historical performance chart and technical data.
  • Performance Analysis:
    • Calculate the daily performance of the global portfolio.
    • Identify and rank the best and worst-performing stocks from the previous day ("Top/Flop Performers").
    • Analyze the current price position of each stock relative to its 52-week highs and lows.

1.3.2. Non-Functional Objectives

  • Reliability and Accuracy: The displayed financial data must be flawless. Calculations must be exact, and data inconsistencies (e.g., currencies, tickers, corrupted input files) must be handled robustly. This is the most important quality objective.
  • Automation: The system must operate without daily manual intervention. Data updates and code deployments must be fully automated.
  • Maintainability: The software architecture must be clean, modular, and easy to understand. This includes maintaining clear documentation and a comprehensive test suite that validates the application's behavior.
  • Security: The application must follow web security best practices to protect user data and access keys to external services.

1.4. Guiding Principles and Architectural Philosophy

To achieve these objectives, the "Augmented Analyst" project was built on a foundation of modern DevOps principles. These architectural decisions are not accidental; they are the result of a commitment to building a professional-quality system.

1.4.1. Infrastructure as Code (IaC): Reliability through Containerization

The project rejects the fragile approach of manual server configuration. The entire application (Python code, database) is encapsulated in Docker containers.

  • Why? This approach ensures that the development, testing, and production environments are strictly identical, eliminating the most common cause of bugs: "it worked on my machine." The configuration is defined in files (Dockerfile, docker-compose.yml), making it versionable, reproducible, and reliable.

1.4.2. Total Automation (CI/CD): The Developer Robot

The project allows no manual deployments. Every code change is managed by a CI/CD (Continuous Integration/Continuous Deployment) pipeline orchestrated by GitHub Actions.

  • Why? Automating deployment via a "robot" eliminates the risk of human error, ensures that every deployment follows the exact same procedure, and allows for the rapid and confident delivery of improvements.

1.4.3. The Permanent Safety Net (Automated Tests)

No line of code is "pushed" to production without being validated by a rigorous suite of automated tests written with Pytest.

  • Why? Tests are the application's "bodyguard." They protect against regressions, validate that new features behave as expected, and serve as living documentation of the system's functionality. This is the guarantee of long-term maintainability.

1.4.4. The Explicit Source of Truth: The Human in Control

For complex business logic subject to interpretation (like matching tickers between different sources or managing currencies), the project adopts a clear principle: the code should not "guess."

  • Why? Data reliability takes precedence over code "magic." It is the user, through enriched configuration files (the portfolio CSV with its mapping columns, the config.ini file), who provides explicit instructions to the system. The code then becomes a simple and reliable executor of these instructions, making the pipeline's behavior predictable and easy to debug.