Explanations

Conceptual guides to help you understand FinWiz's architecture, design decisions, and underlying principles.

What Are Explanations?

Explanations are understanding-oriented discussions that provide context and background. They help you understand why FinWiz works the way it does, not just how to use it.

Available Explanations

Core Architecture

• Architecture Overview - Complete system architecture
• Orchestrator Interactions - How orchestrators work together
• Python Scoring Engine - Scoring engine architecture

Design Philosophy

• Design Principles - Core design philosophy
• Optimization Theory - Optimization approaches
• AI Minimalism (see CLAUDE.md) - AI Minimalism philosophy

Technical Concepts

• Deep Analysis - Deep analysis system explained
• Data Quality - Data quality principles
• Investment Methodology - Investment analysis approach
• Recommendation Engine - How recommendations work

Integration Patterns

• Deep Analysis Integration - Deep analysis integration
• Python Pipeline - Pure Python analysis pipeline
• Notification Service - Notification system

Reporting

• Report Aggregation Guide - Report aggregation
• Report File Structure - Report file organization

Evolution and History

• Test Structure Evolution - Testing evolution
• LLM Model Analysis 2025 - LLM model comparison

Explanation Categories

By Topic

Understanding the System

Start with these to understand FinWiz's design:

1. Architecture Overview - How everything fits together
2. Design Principles - Core philosophy
3. Orchestrator Interactions - Orchestrator framework
4. Python Scoring Engine - Scoring system

Design Decisions

Understand why FinWiz works this way:

1. AI Minimalism (see CLAUDE.md) - Minimize AI, maximize Python
2. Data Quality - Data quality principles
3. Optimization Theory - Optimization approaches

Technical Deep-Dives

Detailed explanations of complex topics:

1. Deep Analysis - Deep analysis system
2. Investment Methodology - Investment analysis
3. Recommendation Engine - Recommendations
4. Python Pipeline - Pure Python analysis

By User Type

For Users

Understand how FinWiz benefits you:

1. Investment Methodology
2. AI Minimalism (see CLAUDE.md)
3. Data Quality
4. Deep Analysis

For Developers

Understand FinWiz's technical architecture:

1. Architecture Overview
2. Orchestrator Interactions
3. Python Scoring Engine
4. Test Structure Evolution

For Architects

Understand design decisions and trade-offs:

1. Design Principles
2. Optimization Theory
3. Notification Service

Key Concepts

AI Minimalism

Core Principle: Use Python for deterministic tasks, AI only where reasoning is required.

Why?

• Performance: 10-20x faster with Python
• Cost: 100% reduction (zero LLM calls for calculations)
• Reliability: Deterministic results, easier testing
• Transparency: Mathematical formulas are auditable

Learn More: AI Minimalism (see CLAUDE.md)

Pydantic-First Design

Core Principle: All data validated with strict Pydantic schemas.

Why?

• Type Safety: Catch errors at validation time
• Documentation: Schemas serve as documentation
• IDE Support: Auto-completion and type checking
• API Stability: Breaking changes detected early

Learn More: Design Principles

File-Based Data Passing

Core Principle: Pass file paths between crews, not large data objects.

Why?

• Context Limits: Avoids LLM context window limits
• Caching: Enables efficient data caching
• Performance: Reduces memory usage
• Debugging: Easy to inspect intermediate results

Learn More: Architecture Overview

Concurrent Execution

Core Principle: Run independent tasks in parallel.

Why?

• Performance: 10-20x speedup for portfolio analysis
• Resource Utilization: Better use of CPU cores
• Scalability: Handles large portfolios efficiently
• User Experience: Faster results

Learn More: Architecture Overview

Architecture Diagrams

System Architecture

Text Only

┌─────────────────────────────────────────────────────────────┐
│                     Flow Orchestrator                        │
│                  (CrewAI Flow - Pydantic State)             │
└────────┬────────────────────────────────────────────┬────────┘
         │                                            │
         ▼                                            ▼
┌──────────────────┐                        ┌──────────────────┐
│   Orchestrators  │                        │   Crews (AI)     │
│  (Business Logic)│                        │  (Analysis)      │
└────────┬─────────┘                        └─────────┬────────┘
         │                                            │
         ▼                                            ▼
┌──────────────────┐                        ┌──────────────────┐
│  Scoring Engine  │                        │      Tools       │
│   (Python)       │                        │  (Data Access)   │
└────────┬─────────┘                        └─────────┬────────┘
         │                                            │
         ▼                                            ▼
┌──────────────────┐                        ┌──────────────────┐
│  Reporting       │                        │   Integration    │
│  (Jinja2)        │                        │  (Data Sources)  │
└──────────────────┘                        └──────────────────┘

Learn More: Architecture Overview

Data Flow

Text Only

Portfolio CSV → Data Accessor → Validation → Cache
                                                ↓
                                           Batch Pre-fetch
                                                ↓
                                    ┌───────────┴───────────┐
                                    ▼                       ▼
                            Deep Analysis           Deep Analysis
                            Crew #1                  Crew #2
                                    ↓                       ↓
                                 Scoring              Scoring
                                 Engine               Engine
                                    ↓                       ↓
                                    └───────────┬───────────┘
                                                ▼
                                         Report Generator
                                                ↓
                                          HTML Reports

Learn More: Data Quality Guide

Design Trade-offs

AI vs Python

Aspect	AI Approach	Python Approach
Speed	Slower (45-90s)	Faster (2-5s)
Cost	$0.05-0.10 per analysis	$0
Consistency	Variable	Deterministic
Reasoning	Excellent	Limited
Testing	Difficult	Easy
Use Cases	Complex analysis	Calculations

Learn More: Design Principles

Batch vs Sequential

Aspect	Batch Processing	Sequential
Speed	10-20x faster	Baseline
Complexity	Higher	Lower
Resource Usage	Higher (parallel)	Lower
Debugging	More difficult	Easier
Best For	Large portfolios	Small portfolios

Learn More: Architecture Overview

Additional Resources

Core Documentation

• User Guide - Complete user documentation
• Developer Guide - Architecture and development

Tutorials

• Getting Started - First-time setup
• First Analysis - Your first analysis

How-To Guides

• Performance Optimization - Optimization
• Batch Processing - High-performance analysis

Reference

• API Reference - API documentation
• CLI Commands - Command reference

Contributing Explanations

Good explanations should:

• Provide Context: Explain why, not just what
• Use Examples: Illustrate concepts with real examples
• Show Trade-offs: Discuss benefits and limitations
• Link to Code: Reference actual implementation
• Stay Current: Update with architectural changes

See Developer Guide for contribution guidelines.

Need Help?

• Understanding concepts: Read the explanations above
• Learning FinWiz: Start with Tutorials
• Solving problems: Check How-To Guides
• Looking up details: See Reference

---

Explore the explanations above to deepen your understanding of FinWiz's architecture and design.