Smoke Signal#

Smoke Signal is an event and RSVP management application that integrates with the AT Protocol (Bluesky). It allows users to create, manage, and respond to events within the AT Protocol ecosystem.

Architecture and Project Structure#

Smoke Signal follows a modern web application architecture designed for scalability and maintainability:

Core Components#

• Web Server (Axum): Handles HTTP requests and responses using the Axum framework
• Template Engine (MiniJinja): Renders HTML templates with dynamic content
• Database Layer (SQLx): SQL toolkit providing type-safe database interactions
• Authentication System: OAuth-based authentication with AT Protocol support
• Internationalization (i18n): Multi-language support using Fluent bundles

Directory Structure#

• /src: Rust source code
  • /bin: Binary executables (smokesignal, crypto, resolve)
  • /http: HTTP route handlers and middlewares
  • /storage: Database models and persistence layer
  • /atproto: AT Protocol specific implementation
• /templates: HTML templates using MiniJinja templating system
• /static: Static assets (CSS, JavaScript, images)
• /i18n: Internationalization resources
• /migrations: SQL database migrations
• /playbooks: Operational guides for deployment and development
• /fixtures: Test data and fixtures

Data Model#

The core data model includes:

• Events: Contains event details, location, time, and other metadata
• RSVPs: User responses to events (going, interested, not going)
• Users: User profiles and authentication information

Key Features in Detail#

1. AT Protocol Integration

   • Seamlessly connects with Bluesky identities
   • Uses DIDs (Decentralized Identifiers) for user identification
   • Supports standard AT Protocol authentication flows

2. Event Management System

   • Creates, updates, and deletes events
   • Supports recurring events
   • Handles time zones intelligently
   • Provides location-based event discovery

3. RSVP Management

   • Tracks user responses to events
   • Provides notifications for event updates
   • Supports private and public RSVP options

4. Responsive UI

   • Mobile-first design using Bulma CSS framework
   • HTMX for dynamic content without heavy JavaScript
   • Progressive enhancement for users without JavaScript

Technology Stack#

• Backend: Rust with Axum web framework
• Database: PostgreSQL for persistent storage
• Caching: Redis/Valkey for fast data retrieval
• Frontend: MiniJinja templates with HTMX for dynamic interactions
• Authentication: OAuth integration with AT Protocol

Prerequisites#

• Rust toolchain (1.83+)
• PostgreSQL database
• Redis or Valkey key-value store
• Docker (for containerized deployment)
• SQLx CLI (cargo install sqlx-cli@0.8.2 --no-default-features --features postgres)

Getting Started#

Local Development#

see playbooks/localdev.md

Configuration#

Smoke Signal is configured through environment variables:

Development#

Building#

# Development build with template reloading
cargo build --bin smokesignal --no-default-features -F reload

# Production build with embedded templates
cargo build --release --bin smokesignal --no-default-features -F embed

Testing#

# Run all tests
cargo test

# Run with specific features
cargo test --no-default-features -F embed

Linting and Code Quality#

# Run clippy linter
cargo clippy

# Check code formatting
cargo fmt --check

Releasing#

To release a new version of Smoke Signal:

1. Update the version in Cargo.toml
2. Update the version in Dockerfile (LABEL org.opencontainers.image.version)
3. Commit the changes: git commit -m "release: X.Y.Z"
4. Tag the commit: git tag -s -m "vX.Y.Z" X.Y.Z
5. Build the container: docker build -t repository/smokesignal:latest .

License#

This project is licensed under the MIT License - see the LICENSE file for details.

Links#

• Homepage
• Repository
• Bug Reports

Traduction Française#

Smoke Signal#

Smoke Signal est une application de gestion d'événements et de RSVP qui s'intègre avec le protocole AT (Bluesky). Elle permet aux utilisateurs de créer, gérer et répondre à des événements au sein de l'écosystème du protocole AT.

Architecture et Structure du Projet#

Smoke Signal suit une architecture d'application web moderne conçue pour la scalabilité et la maintenabilité:

Composants Principaux#

• Serveur Web (Axum): Gère les requêtes et réponses HTTP en utilisant le framework Axum
• Moteur de Template (MiniJinja): Génère des templates HTML avec contenu dynamique
• Couche de Base de Données (SQLx): Toolkit SQL fournissant des interactions avec la base de données typées
• Système d'Authentification: Authentification basée sur OAuth avec support du protocole AT
• Internationalisation (i18n): Support multi-langues utilisant les bundles Fluent

Structure des Répertoires#

• /src: Code source Rust
  • /bin: Exécutables binaires (smokesignal, crypto, resolve)
  • /http: Gestionnaires de routes HTTP et middlewares
  • /storage: Modèles de base de données et couche de persistance
  • /atproto: Implémentation spécifique au protocole AT
• /templates: Templates HTML utilisant le système de templates MiniJinja
• /static: Ressources statiques (CSS, JavaScript, images)
• /i18n: Ressources d'internationalisation
• /migrations: Migrations de base de données SQL
• /playbooks: Guides opérationnels pour le déploiement et le développement
• /fixtures: Données de test et fixtures

Modèle de Données#

Le modèle de données principal comprend:

• Événements: Contient les détails de l'événement, l'emplacement, l'heure et autres métadonnées
• RSVPs: Réponses des utilisateurs aux événements (participation, intéressé, non participation)
• Utilisateurs: Profils utilisateurs et informations d'authentification

Fonctionnalités Principales en Détail#

1. Intégration du Protocole AT

   • Se connecte de manière transparente avec les identités Bluesky
   • Utilise les DIDs (Identifiants Décentralisés) pour l'identification des utilisateurs
   • Supporte les flux d'authentification standard du protocole AT

2. Système de Gestion d'Événements

   • Crée, met à jour et supprime des événements
   • Prend en charge les événements récurrents
   • Gère intelligemment les fuseaux horaires
   • Fournit une découverte d'événements basée sur la localisation

3. Gestion des RSVP

   • Suit les réponses des utilisateurs aux événements
   • Fournit des notifications pour les mises à jour d'événements
   • Prend en charge des options de RSVP privées et publiques

4. Interface Utilisateur Responsive

   • Design mobile-first utilisant le framework CSS Bulma
   • HTMX pour contenu dynamique sans JavaScript lourd
   • Amélioration progressive pour les utilisateurs sans JavaScript

Stack Technologique#

• Backend: Rust avec le framework web Axum
• Base de Données: PostgreSQL pour le stockage persistant
• Mise en Cache: Redis/Valkey pour une récupération rapide des données
• Frontend: Templates MiniJinja avec HTMX pour les interactions dynamiques
• Authentification: Intégration OAuth avec le protocole AT

Prérequis#

• Toolchain Rust (1.83+)
• Base de données PostgreSQL
• Redis ou Valkey pour le stockage clé-valeur
• Docker (pour le déploiement conteneurisé)
• SQLx CLI (cargo install sqlx-cli@0.8.2 --no-default-features --features postgres)

Démarrage#

Développement Local#

voir playbooks/localdev.md

Configuration#

Smoke signal est configuré via des variables d'environnement:

Développement#

Compilation#

# Compilation de développement avec rechargement des templates
cargo build --bin smokesignal --no-default-features -F reload

# Compilation de production avec templates embarqués
cargo build --release --bin smokesignal --no-default-features -F embed

Tests#

# Exécuter tous les tests
cargo test

# Exécuter avec des fonctionnalités spécifiques
cargo test --no-default-features -F embed

Linting et Qualité de Code#

# Exécuter le linter clippy
cargo clippy

# Vérifier le formatage du code
cargo fmt --check

Publication#

Pour publier une nouvelle version de Smoke signal:

1. Mettre à jour la version dans Cargo.toml
2. Mettre à jour la version dans Dockerfile (LABEL org.opencontainers.image.version)
3. Commiter les changements: git commit -m "release: X.Y.Z"
4. Tagger le commit: git tag -s -m "vX.Y.Z" X.Y.Z
5. Construire le conteneur: docker build -t repository/smokesignal:latest .

Licence#

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

Liens#

• Page d'accueil
• Dépôt
• Signalement de bugs