# Shannon's Equation for Dummies

**Educational Web Application for Satellite Communications**

Exploration from Claude Shannon's initial theory to its practical application to satellite communications.

## 🚀 Stack

- **Frontend**: [Streamlit](https://streamlit.io) with [Plotly](https://plotly.com) interactive charts
- **Backend**: Python 3.11+ with scientific libraries (numpy, scipy, itur, astropy)
- **Database**: SQLite for community contributions
- **Deployment**: Docker + docker-compose, designed for 24/7 multi-user operation

## 📁 Project Structure

```
.
├── app.py                      # Main Streamlit entry point
├── core/                       # Core business logic
│   ├── calculations.py         # Shannon equations & satellite link budget
│   ├── database.py            # SQLite contribution management
│   └── help_texts.py          # Educational help content
├── views/                      # UI pages
│   ├── theory.py              # Theoretical exploration (Shannon limit)
│   ├── real_world.py          # Real-world link budget calculator
│   └── contributions.py       # Community knowledge database
├── .streamlit/config.toml     # Streamlit configuration
├── Dockerfile                 # Container image definition
├── docker-compose.yml         # Orchestration with nginx-proxy
└── requirements.txt           # Python dependencies
```

## 🛠️ Local Development

### Prerequisites
- Python 3.11+
- pip

### Setup

```bash
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the app
streamlit run app.py
```

The app will open at `http://localhost:8501`

## 🐳 Docker Deployment

### Build and run

```bash
docker-compose up -d
```

The app will be available at `http://localhost:8080`

### Environment

- **Port**: 8080 (configurable in `.streamlit/config.toml`)
- **Health Check**: `/_stcore/health`
- **Data Persistence**: SQLite databases stored in `shannon_data` volume

### Production Setup

The `docker-compose.yml` is configured for nginx-proxy:
- Network: `nginx-proxy`
- Virtual host: `shannon.antopoid.com`
- HTTPS ready (with appropriate Let's Encrypt configuration)

## 📚 Features

### 1. Theoretical Exploration
- Shannon capacity calculation (C = BW × log₂(1 + C/N))
- Bandwidth and power sensitivity analysis
- Bit rate factor maps
- Interactive Plotly graphs

### 2. Real-World Link Budget
- Complete satellite link calculation
- ITU-R atmospheric attenuation models
- Receiver noise and baseband impairments
- Practical Shannon limits with penalties

### 3. Community Contributions
- Collaborative knowledge database
- Search and filter capabilities
- Read/Write/Delete permissions

## 🎓 Educational Value

The application provides extensive background information accessible through help expanders on every input/output, covering:
- Shannon's theorem and its implications
- Satellite communication fundamentals
- Atmospheric propagation effects
- Modulation and coding schemes
- Real-world system design trade-offs

## 📝 License & Author

© 2021-2026 · Shannon Equation for Dummies  
Created by JPC (February 2021)  
Migrated to Streamlit (2026)