archshots - Architecture Screenshot Tool¶

Automated screenshot capture and documentation tool for system architecture visualization.
Overview¶

archshots captures screenshots of system components, services, and infrastructure to create visual documentation. It automatically detects running services, captures relevant interfaces, and organizes screenshots for architecture documentation.
When to use: Documenting system architecture, creating visual overviews of running services, or maintaining visual records of system states.
Usage¶

archshots [options] [targets]
```bash

### Options

- `-o DIR`: Output directory (default: ./archshots)
- `-f FORMAT`: Image format (png, jpg, pdf)
- `-q QUALITY`: Image quality (1-100, default: 90)
- `-d DELAY`: Delay between captures (seconds)
- `-s`: Silent mode (no progress output)
- `-v`: Verbose output
- `-n`: Dry run (show what would be captured)
- `-h`: Show help

### Targets

- `desktop`: Desktop screenshot
- `windows`: All application windows
- `services`: Running system services
- `network`: Network configuration
- `processes`: Process list visualization
- `logs`: Log file previews
- `config`: Configuration files
- `all`: All targets

## Examples

### Basic Usage

```bash
# Capture desktop
archshots desktop

# Capture all windows
archshots windows

# Full system capture
archshots all
```bash

### Advanced Capture

```bash
# Custom output directory
archshots -o ~/docs/architecture/ all

# High quality PNG
archshots -f png -q 100 desktop

# Service documentation
archshots services network
```bash

### Automated Capture

```bash
# Capture every 5 minutes
while true; do
    archshots -o "capture-$(date +%Y%m%d-%H%M%S)" desktop
    sleep 300
done

# Capture before/after changes
archshots -o before desktop
# Make system changes...
archshots -o after desktop
```bash

## How It Works

### Capture Pipeline

1. **Target Discovery**: Identifies what to capture
2. **Preparation**: Sets up capture environment
3. **Screenshot Capture**: Takes screenshots
4. **Metadata Collection**: Gathers system information
5. **Organization**: Structures output files
6. **Documentation**: Generates index and reports

### Supported Targets

#### Desktop

- **Full desktop**: Complete screen capture
- **Active window**: Currently focused application
- **Multiple displays**: All connected monitors

#### Windows

- **Application windows**: Individual app screenshots
- **Window list**: Organized by application
- **Window details**: Size, position, title

#### Services

- **System services**: Running daemons and services
- **Web services**: Browser screenshots of local services
- **Database services**: Connection and status
- **API endpoints**: Service documentation pages

#### Network

- **Network interfaces**: IP configuration
- **Routing tables**: Network routes
- **Firewall rules**: Security configuration
- **Service ports**: Listening services

#### Processes

- **Process tree**: Hierarchical process view
- **Resource usage**: CPU, memory, I/O
- **Process details**: Command lines, PIDs
- **Service mapping**: Processes to services

#### Logs

- **System logs**: Journal/systemd logs
- **Application logs**: Service-specific logs
- **Error highlights**: Recent errors and warnings
- **Log analysis**: Pattern recognition

#### Configuration

- **System config**: Key configuration files
- **Service config**: Application settings
- **Network config**: Interface and routing config
- **Security config**: Access controls

## Configuration

### Configuration File

```toml
# ~/.config/archshots/config.toml
[capture]
format = "png"
quality = 90
delay = 1
max_width = 1920
max_height = 1080

[targets]
desktop = { enabled = true, displays = "all" }
windows = { enabled = true, active_only = false }
services = { enabled = true, local_only = true }

[output]
directory = "./archshots"
naming = "timestamp"
organize = "target"

[metadata]
system_info = true
timestamps = true
git_info = true
```bash

### Environment Variables

```bash
# Output settings
export ARCHSHOTS_OUTPUT_DIR="~/architecture"
export ARCHSHOTS_FORMAT="jpg"
export ARCHSHOTS_QUALITY="85"

# Capture options
export ARCHSHOTS_DELAY="2"
export ARCHSHOTS_SILENT="1"

# Browser settings (for web services)
export ARCHSHOTS_BROWSER="chromium"
export ARCHSHOTS_TIMEOUT="30"
```bash

## Dependencies

### Required

- **scrot**: Screenshot capture (Linux)
- **screencapture**: Screenshot capture (macOS)
- **import**: ImageMagick screenshot (fallback)
- **xwininfo**: Window information
- **wmctrl**: Window management

### Optional

- **chromium/firefox**: Web service screenshots
- **curl/wget**: Service testing
- **netstat/ss**: Network information
- **systemctl**: Service management
- **ps**: Process information

## Troubleshooting

### No Screenshots Captured

**Symptom:** Empty output directory

**Cause:** Screenshot tool not available or permissions

**Fix:**

```bash
# Check available tools
which scrot screencapture import

# Install screenshot tool
sudo apt install scrot  # Ubuntu/Debian
brew install imagemagick  # macOS

# Check display permissions
xhost +  # For X11
```bash

### Black Screenshots

**Symptom:** Screenshots are black/empty

**Cause:** Display server issues or permissions

**Fix:**

```bash
# Check display
echo $DISPLAY

# For Wayland
export ARCHSHOTS_TOOL="grim"

# For X11 with permissions
xhost +local:

# Test screenshot manually
scrot test.png
```bash

### Service Capture Fails

**Symptom:** Service screenshots not captured

**Cause:** Services not accessible or browser issues

**Fix:**

```bash
# Check service status
systemctl status myservice

# Test service access
curl http://localhost:8080

# Configure browser
export ARCHSHOTS_BROWSER="firefox"
export ARCHSHOTS_HEADLESS="1"
```bash

### Permission Issues

**Symptom:** "Permission denied" errors

**Cause:** Insufficient privileges for system access

**Fix:**

```bash
# Run with sudo for system info
sudo archshots services

# Check file permissions
ls -la /var/log/

# Add to sudoers for specific commands
# User can run specific archshots commands without password
```bash

### Large File Sizes

**Symptom:** Screenshot files too large

**Cause:** High quality or uncompressed format

**Fix:**

```bash
# Reduce quality
archshots -q 75 desktop

# Use JPG format
archshots -f jpg desktop

# Resize images
mogrify -resize 50% archshots/*.png
```bash

## Performance

### Capture Times

| Target        | Time   | File Size |
| ------------- | ------ | --------- |
| Desktop       | 1-2s   | 500KB-2MB |
| Windows (5)   | 5-10s  | 2-5MB     |
| Services (10) | 30-60s | 5-15MB    |
| Full system   | 2-5min | 20-100MB  |

### Resource Usage

- **Memory**: 50-200MB during capture
- **CPU**: 10-50% during active capture
- **Disk**: Output size depends on targets
- **Network**: Minimal (for service testing)

## Integration

### With Documentation

```bash
#!/bin/bash
# Generate architecture documentation
PROJECT="my-system"

# Capture current state
archshots -o "docs/architecture/$PROJECT" all

# Generate report
archshots --report > "docs/architecture/$PROJECT-report.md"

# Commit to documentation
cd docs
git add architecture/
git commit -m "Update architecture screenshots"
```bash

### With Monitoring

```bash
# Automated monitoring screenshots
*/5 * * * * /usr/local/bin/archshots -o "/var/log/archshots/$(date +\%Y\%m\%d)" desktop
```bash

### With CI/CD

```bash
# Capture test environment
archshots -o test-results/architecture services network

# Compare architectures
diff -r archshots-baseline/ archshots-current/
```bash

### With System Administration

```bash
# Before/after system changes
archshots -o before-upgrade all
# Perform system upgrade...
archshots -o after-upgrade all

# Troubleshooting captures
archshots desktop windows services > troubleshooting-$(date +%s).tar.gz
```bash

## Output Structure

```bash
archshots-20240101-120000/
├── desktop/
│   ├── screenshot-1.png
│   └── screenshot-1.metadata.json
├── windows/
│   ├── firefox-1234.png
│   ├── terminal-5678.png
│   └── windows.metadata.json
├── services/
│   ├── apache2.png
│   ├── mysql.png
│   └── services.metadata.json
├── network/
│   ├── interfaces.png
│   └── network.metadata.json
├── index.html
├── report.md
└── metadata.json
```bash

## Technical Details

### Image Capture Methods

#### Linux (X11)

```bash
# scrot for full screen
scrot -q 90 screenshot.png

# Import for windows
import -window 0x12345678 window.png
```bash

#### macOS

```bash
# screencapture
screencapture -x screenshot.png
```bash

#### Wayland

```bash
# grim/slurp
grim -g "$(slurp)" screenshot.png
```bash

### Metadata Collection

```json
{
  "capture": {
    "timestamp": "2024-01-01T12:00:00Z",
    "tool": "scrot",
    "format": "png",
    "quality": 90
  },
  "system": {
    "os": "Ubuntu 22.04",
    "kernel": "5.15.0",
    "display": ":0"
  },
  "target": {
    "type": "desktop",
    "dimensions": "1920x1080",
    "displays": 1
  }
}
```bash

### Web Service Capture

- **Headless browser**: Chromium/Firefox in headless mode
- **Service detection**: Port scanning and service identification
- **Screenshot timing**: Wait for page load completion
- **Error handling**: Timeout and retry logic

### Report Generation

- **HTML index**: Web-viewable gallery
- **Markdown report**: Text summary with links
- **JSON metadata**: Structured data for automation
- **Statistics**: File counts, sizes, capture times

## See Also

- **[sshot](sshot.md)** - Simple screenshot tool
- **[syssnap](syssnap.md)** - System snapshot tool
- **[auditenv](auditenv.md)** - Environment auditing
- **[Architecture Documentation](../../README.md#architecture)** - Documentation guide