🏗️ Arquitetura Técnica

Visão Geral

O Crypto Dashboard é construído com uma arquitetura em camadas, separando claramente a interface do utilizador, lógica de negócio, acesso a dados e integrações externas.

┌─────────────────────────────────────────────────┐
│         Frontend (Streamlit UI)                 │
│  app.py, pages/*, components                    │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│         Services (Business Logic)               │
│  services/shares.py                             │
│  services/snapshots.py                          │
│  services/coingecko.py                          │
│  services/calculations.py                       │
│  services/fees.py                               │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│         Database Layer                          │
│  database/connection.py                         │
│  database/users.py                              │
│  database/portfolio.py                          │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│         PostgreSQL Database                     │
│  Tables, Indexes, Constraints                   │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│         External APIs                           │
│  CoinGecko API (preços)                         │
└─────────────────────────────────────────────────┘

Stack Tecnológico

Backend

Frontend

Integrações

Estrutura de Diretórios

CryptoDashboard/
├── app.py                          # Entry point da aplicação
├── config.py                       # Configurações globais
├── requirements.txt                # Dependências Python
│
├── auth/                           # Autenticação e sessão
│   ├── login.py                    # Lógica de login
│   ├── register.py                 # Registo de utilizadores
│   └── session_manager.py          # Gestão de sessão Streamlit
│
├── database/                       # Camada de acesso a dados
│   ├── connection.py               # Pool de conexões PostgreSQL
│   ├── users.py                    # Queries relacionadas a utilizadores
│   ├── portfolio.py                # Queries de portfólio
│   └── tablesv2.sql                # Schema completo da BD (V2)
│
├── pages/                          # Páginas da aplicação (routing)
│   ├── analytics.py                # Página de análise (legacy)
│   ├── portfolio.py                # Gestão de portfólio
│   ├── portfolio_analysis.py       # Dashboard de análise completo
│   ├── settings.py                 # Configurações
│   └── users.py                    # Gestão de utilizadores (admin)
│
├── services/                       # Lógica de negócio
│   ├── calculations.py             # Cálculos financeiros
│   ├── coingecko.py                # Cliente CoinGecko API
│   ├── fees.py                     # Gestão de taxas
│   ├── minswap.py                  # Integração MinSwap
│   ├── shares.py                   # Sistema de shares/NAV ⭐
│   └── snapshots.py                # Cache de preços históricos ⭐
│
├── utils/                          # Utilitários
│   ├── formatters.py               # Formatação de números/datas
│   └── security.py                 # Funções de segurança
│
└── wiki/                           # Documentação
    ├── 01-arquitetura.md
    ├── 02-shares-nav.md
    └── ...

Base de Dados

Schema Principal

Tabelas de Utilizadores

-- Autenticação e perfil base
t_users
├── user_id (PK)
├── username (unique)
├── password_hash
├── email (unique)
└── is_admin (boolean)

-- Perfil detalhado
t_user_profile
├── profile_id (PK)
├── user_id (FK → t_users)
├── full_name
├── birth_date
├── gender
└── address

Tabelas de Capital

-- Movimentos de capital (depósitos/levantamentos)
t_user_capital_movements
├── movement_id (PK)
├── user_id (FK → t_users)
├── movement_date
├── credit (depósito)
├── debit (levantamento)
└── notes

-- Sistema de shares (ownership) ⭐
t_user_shares
├── share_id (PK)
├── user_id (FK → t_users)
├── movement_date
├── movement_type ('deposit' | 'withdrawal')
├── amount_eur
├── nav_per_share (preço da share no momento)
├── shares_amount (positivo ou negativo)
├── total_shares_after (acumulado do user)
├── fund_nav (NAV total do fundo)
└── notes

Tabelas de Ativos e Transações

-- Ativos disponíveis
t_assets
├── asset_id (PK)
├── symbol (e.g., 'BTC', 'ETH', 'EUR')
├── name
├── chain
├── coingecko_id
└── is_stablecoin (BOOLEAN)

-- Exchanges e Contas
t_exchanges
├── exchange_id (PK)
├── name
└── category

t_exchange_accounts
├── account_id (PK)
├── exchange_id (FK → t_exchanges)
├── user_id (FK → t_users)
├── name (rótulo da conta)
└── account_category (ex.: Spot, Earn, Wallet)

Cache de Preços ⭐

-- Snapshots de preços históricos
t_price_snapshots
├── snapshot_id (PK)
├── asset_id (FK → t_assets)
├── snapshot_date
├── price
├── vs_currency ('eur', 'usd', etc)
└── created_at

-- Index para busca rápida
CREATE INDEX idx_price_snapshots_lookup 
ON t_price_snapshots(asset_id, snapshot_date, vs_currency);

Componentes Principais

1. Sistema de Autenticação

Localização: auth/

Fluxo:

  1. Utilizador submete credenciais
  2. login.py valida contra t_users (bcrypt hash)
  3. session_manager.py cria sessão Streamlit
  4. Sessão armazena: user_id, username, is_admin
  5. Decorator @require_auth protege páginas

Segurança:

← Voltar ao Dashboard Sistema de Shares/NAV →