ECTLogger Development Guide

Project Structure

ectlogger/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py              # FastAPI application entry point
│   │   ├── config.py            # Configuration settings
│   │   ├── database.py          # Database connection and session
│   │   ├── models.py            # SQLAlchemy models
│   │   ├── schemas.py           # Pydantic schemas for validation
│   │   ├── auth.py              # Authentication utilities
│   │   ├── dependencies.py      # FastAPI dependencies
│   │   ├── email_service.py     # Email notification service
│   │   └── routers/
│   │       ├── __init__.py
│   │       ├── auth.py          # Authentication endpoints
│   │       ├── users.py         # User management endpoints
│   │       ├── nets.py          # Net management endpoints
│   │       ├── check_ins.py     # Check-in endpoints
│   │       └── frequencies.py   # Frequency management endpoints
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   └── Navbar.tsx       # Navigation bar component
│   │   ├── contexts/
│   │   │   └── AuthContext.tsx  # Authentication context
│   │   ├── pages/
│   │   │   ├── Login.tsx        # Login page
│   │   │   ├── Dashboard.tsx    # Main dashboard
│   │   │   ├── NetView.tsx      # Net details and check-ins
│   │   │   └── CreateNet.tsx    # Create new net
│   │   ├── services/
│   │   │   └── api.ts           # API client and endpoints
│   │   ├── App.tsx              # Main application component
│   │   ├── main.tsx             # Application entry point
│   │   └── vite-env.d.ts        # TypeScript declarations
│   ├── index.html
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
├── .env.example
├── .gitignore
├── LICENSE
├── README.md
└── MANUAL-INSTALLATION.md

Key Features Implemented

Authentication

Magic link email authentication
OAuth2 support (Google, Microsoft, GitHub)
JWT token-based authentication
Role-based access control (Admin, NCS, User, Guest)

Net Management

Create, update, and delete nets
Start and close nets
Multi-frequency support with active frequency tracking
Net status tracking (Draft, Scheduled, Active, Closed)
NCS, logger, and relay role assignments
Net templates for reusable configurations
ICS-309 communication log mode

Multi-NCS Operations

Multiple NCS operators per net
Per-NCS frequency claiming (NetRole.active_frequency_id)
NCS color coding (unique colors for each NCS)
Visual hierarchy (👑 primary NCS, 🤴 secondary NCS)
Automatic frequency assignment when NCS creates check-ins

Check-ins

Create check-ins with required and optional fields
Recheck tracking (stations checking in multiple times)
Real-time updates via WebSocket
Status tracking (Checked In, Listening, Available, Away, Checked Out)
Frequency tracking per check-in (frequency_id and available_frequency_ids)
Bulk check-in for multiple stations
Search and filter by callsign, name, location, or frequency

Real-time Features

WebSocket connections for live net updates
Instant check-in notifications
Real-time frequency changes
Check-in deletion broadcasts
Live chat functionality
Online user tracking

Email Notifications

Magic link authentication emails
Net start notifications to subscribers
Net invitation emails
Net closure logs emailed to NCS

API Endpoints

Authentication (`/auth`)

POST /auth/magic-link/request - Request magic link
POST /auth/magic-link/verify - Verify magic link
GET /auth/oauth/{provider} - OAuth login
GET /auth/oauth/{provider}/callback - OAuth callback
GET /auth/me - Get current user

Users (`/users`)

GET /users/me - Get current user profile
PUT /users/me - Update current user profile
GET /users/ - List all users (admin)
GET /users/{user_id} - Get user by ID
PUT /users/{user_id}/role - Update user role (admin)

Nets (`/nets`)

POST /nets/ - Create net
GET /nets/ - List nets (with status filter)
GET /nets/{net_id} - Get net details (includes can_manage permission flag)
GET /nets/{net_id}/stats - Get net statistics and online users
PUT /nets/{net_id} - Update net
POST /nets/{net_id}/start - Start net
POST /nets/{net_id}/close - Close net
DELETE /nets/{net_id} - Delete net
GET /nets/{net_id}/export/csv - Export check-ins as CSV
GET /nets/{net_id}/export/ics309 - Export as ICS-309 communication log

Net Roles (`/nets/{net_id}/roles`)

GET /nets/{net_id}/roles - List roles for a net
POST /nets/{net_id}/roles - Assign role to user
DELETE /nets/{net_id}/roles/{role_id} - Remove role
PUT /nets/{net_id}/roles/{role_id}/frequency/{frequency_id} - Claim frequency as NCS
DELETE /nets/{net_id}/roles/{role_id}/frequency - Release claimed frequency

Check-ins (`/check-ins`)

POST /check-ins/nets/{net_id}/check-ins - Create check-in
GET /check-ins/nets/{net_id}/check-ins - List check-ins
GET /check-ins/check-ins/{check_in_id} - Get check-in
PUT /check-ins/check-ins/{check_in_id} - Update check-in
DELETE /check-ins/check-ins/{check_in_id} - Delete check-in (broadcasts via WebSocket)

Frequencies (`/frequencies`)

POST /frequencies/ - Create frequency
GET /frequencies/ - List frequencies
GET /frequencies/{frequency_id} - Get frequency
DELETE /frequencies/{frequency_id} - Delete frequency

Templates (`/templates`)

GET /templates/ - List net templates
POST /templates/ - Create template from net
GET /templates/{template_id} - Get template
DELETE /templates/{template_id} - Delete template

Statistics (`/statistics`)

GET /statistics/platform - Platform-wide statistics
GET /statistics/user/{user_id} - User participation statistics

WebSocket

WS /ws/nets/{net_id}?token={jwt} - Real-time net updates
- Message types: check_in, check_in_deleted, status_change, role_change, active_frequency, chat_message, net_started, active_speaker

Database Models

User

Authentication and profile information
Role assignment (Admin, NCS, User, Guest)
Email and SMS notification preferences
SKYWARN spotter number

Net

Net metadata and status
Owner and frequency assignments
Start and close timestamps
Active frequency tracking

CheckIn

Station information (callsign, name, location)
Required and optional fields
Status and recheck tracking
Frequency assignment per check-in

Frequency

Frequency and mode information
Many-to-many relationship with nets

NetRole

User role assignments for specific nets
NCS, Logger, Relay designations

CustomField & CustomFieldValue

Dynamic form field creation
Field type support (text, number, textarea, select)
Per-net field requirements

ChatMessage

Real-time chat for active nets
Message history

Adding New Features

Adding a New Field to Check-ins

Backend: Update models.py

# In CheckIn model
new_field = Column(String(255))

Backend: Update schemas.py

# In CheckInBase schema
new_field: Optional[str] = None

Frontend: Update check-in form in NetView.tsx

<TextField
  label="New Field"
  value={checkInForm.new_field}
  onChange={(e) => setCheckInForm({...checkInForm, new_field: e.target.value})}
/>

Adding Custom Reports

Create new router in backend/app/routers/reports.py
Add database queries for report data
Create frontend page in frontend/src/pages/Reports.tsx
Add route to App.tsx

Adding SMS Notifications

Integrate SMS service (Twilio, AWS SNS)
Update email_service.py to include SMS sending
Add SMS gateway configuration to user profiles
Update notification triggers to send both email and SMS

Testing

Backend Testing

cd backend
pip install pytest pytest-asyncio httpx
pytest

Frontend Testing

cd frontend
npm install --save-dev vitest @testing-library/react
npm test

Code Style

Backend (Python)

Follow PEP 8
Use type hints
Async/await for database operations
Comprehensive error handling

Frontend (TypeScript)

Use TypeScript strict mode
Functional components with hooks
Material-UI design system
Proper prop typing

Contributing

Fork the repository
Create a feature branch
Make your changes
Write tests
Submit a pull request

Common Development Tasks

Adding a New Page

Create component in frontend/src/pages/
Add route in App.tsx
Add navigation link if needed

Adding a New API Endpoint

Define schema in schemas.py
Add route in appropriate router file
Update API client in frontend/src/services/api.ts
Use in frontend components

Database Migrations (Future Enhancement)

Consider adding Alembic for database migrations:

cd backend
alembic init alembic
alembic revision --autogenerate -m "Initial migration"
alembic upgrade head

Performance Considerations

Use database indexes on frequently queried fields
Implement pagination for large lists
Use WebSocket selectively to reduce server load
Cache frequently accessed data
Optimize database queries with proper relationships

Security Best Practices

Always use HTTPS in production
Validate all user inputs
Use parameterized queries (SQLAlchemy handles this)
Implement rate limiting for API endpoints
Regularly update dependencies
Use environment variables for sensitive data
Implement proper CORS policies

🗺️ Roadmap

Future enhancements planned:

Completed

~~Participant station mapping~~ ✅

In Progress / Planned

Progressive Web App (PWA) for offline capability
SMS notifications via Twilio/AWS SNS
Advanced reporting and analytics
Export logs in multiple formats (CSV, PDF)
Mobile native apps (iOS/Android)
Integration with amateur radio logging software
Voice check-in via phone bridge
Automated NCS assistant features

Stretch Goals

TUI/Packet Radio Client — Terminal-based client for packet radio and low-bandwidth operations

✅ Tested Environments

Environment	Status	Notes
Debian Trixie	✅ Tested	Python 3.13, production with Caddy reverse proxy
Windows 11	✅ Tested	Development with PowerShell scripts
Host Migration	✅ Tested	LAN to production domain migration
Windows Server	⬜ Untested	Should work with PowerShell scripts

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

ECTLogger Development Guide

Project Structure

Key Features Implemented

Authentication

Net Management

Multi-NCS Operations

Check-ins

Real-time Features

Email Notifications

API Endpoints

Authentication (/auth)

Users (/users)

Nets (/nets)

Net Roles (/nets/{net_id}/roles)

Check-ins (/check-ins)

Frequencies (/frequencies)

Templates (/templates)

Statistics (/statistics)

WebSocket

Database Models

User

Net

CheckIn

Frequency

NetRole

CustomField & CustomFieldValue

ChatMessage

Adding New Features

Adding a New Field to Check-ins

Adding Custom Reports

Adding SMS Notifications

Testing

Backend Testing

Frontend Testing

Code Style

Backend (Python)

Frontend (TypeScript)

Contributing

Common Development Tasks

Adding a New Page

Adding a New API Endpoint

Database Migrations (Future Enhancement)

Performance Considerations

Security Best Practices

🗺️ Roadmap

Completed

In Progress / Planned

Stretch Goals

✅ Tested Environments

🤝 Contributing

Code Style

Backend (Python)

Frontend (TypeScript)

Authentication (`/auth`)

Users (`/users`)

Nets (`/nets`)

Net Roles (`/nets/{net_id}/roles`)

Check-ins (`/check-ins`)

Frequencies (`/frequencies`)

Templates (`/templates`)

Statistics (`/statistics`)