netviz/Readme.md

# NetViz: Secure Network Documentation & Visualization Tool

A security-focused web application for documenting, visualizing, and managing network topologies with minimal JavaScript and a modern UI.

## Features

- **Security-First Architecture**
  - OWASP Top 10 protections
  - Secure session management
  - CSRF protection
  - Bcrypt password hashing
  - Rate limiting for auth endpoints
  - SQL injection protection

- **Modern, Minimal UI**
  - HTMX for dynamic functionality
  - Tailwind CSS with dark/light mode
  - Responsive, mobile-first design
  - Accessible components

- **Core Functionality**
  - User authentication system
  - Network topology management
  - Interactive visualization
  - Firewall rule documentation
  - Data import/export (JSON, CSV)

- **Deployment Ready**
  - Docker and docker-compose configuration
  - PostgreSQL integration
  - Comprehensive logging
  - Health check endpoints

## Project Structure

```
/netviz/
├── app/
│   ├── auth/                  # Authentication blueprints and views
│   ├── core/                  # Core application functionality
│   ├── api/                   # API endpoints
│   ├── models/                # SQLAlchemy models
│   ├── templates/             # Jinja2 templates
│   ├── static/                # Static assets
│   ├── utils/                 # Utility functions
│   ├── __init__.py            # Application factory
│   ├── extensions.py          # Flask extensions
│   └── config.py              # Configuration classes
├── tests/                     # Pytest test suite
├── migrations/                # Alembic database migrations
├── docker/                    # Docker-related files
├── .env.sample                # Sample environment variables
├── requirements.txt           # Python dependencies
├── requirements-dev.txt       # Development dependencies
├── Dockerfile                 # Production Dockerfile
├── docker-compose.yml         # Docker Compose configuration
└── README.md                  # Project documentation
```

## Getting Started

### Prerequisites

- Python 3.9+
- Docker and Docker Compose
- Git

### Local Development Setup

1. Clone the repository
   ```bash
   git clone https://github.com/yourusername/netviz.git
   cd netviz
   ```

2. Create and activate a virtual environment
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. Install dependencies
   ```bash
   pip install -r requirements.txt
   pip install -r requirements-dev.txt
   ```

4. Set up environment variables
   ```bash
   cp .env.sample .env
   # Edit .env with your configuration
   ```

5. Initialize the database
   ```bash
   flask db upgrade
   ```

6. Run the development server
   ```bash
   flask run --debug
   ```

### Docker Deployment

1. Build and start the containers
   ```bash
   docker-compose up -d
   ```

2. Access the application at http://localhost:5000

## Security Features

- **Authentication**
  - Bcrypt password hashing
  - Session-based authentication with secure cookies
  - Password reset functionality
  - Account lockout after failed attempts

- **Protection Mechanisms**
  - CSRF tokens for all forms
  - Content Security Policy (CSP)
  - XSS protection
  - SQL injection prevention
  - Rate limiting
  - Input validation and sanitization

## Development Guidelines

- Follow PEP 8 style guide
- Include type hints for all functions
- Write docstrings for all modules, classes, and functions
- Maintain test coverage above 90%
- Use atomic commits with descriptive messages

## Testing

Run the test suite with pytest:

```bash
pytest
```

Generate a coverage report:

```bash
pytest --cov=app --cov-report=html
```

## Color Scheme

The application uses a professional color palette that works well in both light and dark modes:

- **Primary**: #3B82F6 (blue-500)
- **Secondary**: #10B981 (emerald-500)
- **Accent**: #8B5CF6 (violet-500)
- **Dark Background**: #111827 (gray-900)
- **Light Background**: #F9FAFB (gray-50)
- **Dark Text**: #1F2937 (gray-800)
- **Light Text**: #F9FAFB (gray-50)

## License

[MIT License](LICENSE)

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request