# fcopulgar/stock-manager-go architecture

> Architecture diagram of the GitHub repository fcopulgar/stock-manager-go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fcopulgar/stock-manager-go
- Repository: https://github.com/fcopulgar/stock-manager-go

## Overview

##### Project Overview
- This is a command‐line application for managing stock portfolios. It allows users to view and create portfolios (both manually and randomly) and calculate APR. The application fetches data (S&P 500 symbols and prices) from an external financial data API. Its architecture is modular, separating CLI interactions, business/service logic, data persistence (SQLite), and external service integration.

##### Analyzing the File Structure
- Top-Level Organization:
- Files like .env.example, Dockerfile, docker-compose.yml, go.mod hint at containerized deployment and dependency management.
- The “cmd” directory houses the CLI entry point and related handlers, which are crucial for managing user input.
- The “api” folder contains code that interacts with external endpoints (like fetching S&P 500 symbols and price data).
- “config” contains configuration management and testing around it.
- “models” defines domain objects such as “portfolio” and “stock”.
- “repositories” implement data persistence (with a focus on SQLite) to store and retrieve portfolio data.
- “services” encapsulate the core business logic for portfolio management and the communication with external APIs.

##### Key Components
a. CLI & Handlers:
- User interface (command-line) where user inputs are processed.
- This interacts with PortfolioService for executing commands such as view, create, or APR calculation.

b. PortfolioService:
- Central business logic component that manages the interaction between the CLI and backend subsystems.
- It coordinates with both the Repository and the StockService.

c. StockService:
- Responsible for fetching data (e.g., stock prices, S&P 500 symbols) by connecting to external API endpoints.

d. PortfolioRepository:
- Handles data persistence using SQLite to store and retrieve portfolio and stock information.

e. External API:
- Represents external dependencies from which stock data (prices and symbols) are fetched.

f. Database:
- A SQLite database (or file, e.g., portfolios.db) for persisting portfolio records.

##### Relationships and Interactions
- The CLI component (contained in “cmd/cli”) passes user commands to the service layer.
- The PortfolioService executes business logic by:
- Calling the StockService to retrieve stock data from external APIs (found in “api/” and “services/financialmodelingprep_service.go”).
- Interacting with the PortfolioRepository (in “repositories/”) to perform CRUD operations on data.
- The PortfolioRepository interfaces with an SQLite database.
- Configuration settings (in “config/”) and environment variables (from the .env file) influence how external API calls are authenticated.

- Below it, illustrate the CLI & Handlers block.
- This block with the PortfolioService block in the middle.
- Branch out from PortfolioService toward:
- On one side, the Repository (leading to the SQLite DB).
- On the other side, the StockService (leading further to the external API block).
- With notes on “configuration” to remind of the role env variables and config files play.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        U["User Input"]:::cli
        CLI["CLI & Handlers"]:::cli
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        PS["PortfolioService"]:::service
        SS["StockService"]:::service
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        PR["PortfolioRepository"]:::repo
        DB["SQLite Database"]:::data
    end

    %% External Integration
    subgraph "External Integration"
        API["External API"]:::external
    end

    %% Connections
    U -->|"inputs"| CLI
    CLI -->|"calls"| PS
    PS -->|"retrievesStockData"| SS
    PS -->|"accessesData"| PR
    SS -->|"fetchesFrom"| API
    PR -->|"persistsTo"| DB

    %% Click Events
    click CLI "https://github.com/fcopulgar/stock-manager-go/tree/main/cmd/cli"
    click PS "https://github.com/fcopulgar/stock-manager-go/blob/main/services/portfolio_service.go"
    click SS "https://github.com/fcopulgar/stock-manager-go/blob/main/services/financialmodelingprep_service.go"
    click API "https://github.com/fcopulgar/stock-manager-go/blob/main/api/sp500.go"
    click PR "https://github.com/fcopulgar/stock-manager-go/blob/main/repositories/sqlite_portfolio_repository.go"

    %% Styles
    classDef cli fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef service fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef repo fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
    classDef external fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef data fill:#f9cac8,stroke:#c0392b,stroke-width:2px;
```
