Design Decisions

Core Philosophy

Snek is built on a set of guiding principles that inform every technical and design decision:

• Privacy First: No tracking, no analytics, no email required. User data belongs to users.
• Performance Focus: Fast is a feature. Minimal dependencies, optimized code paths.
• Simplicity Over Complexity: Prefer straightforward solutions. Complexity must justify itself.
• Self-Hosting First: The platform should be trivial to deploy and maintain independently.
• No Framework Lock-in: Avoid dependencies that impose architectural constraints.

Technical Decisions

Why aiohttp Over Flask/Django

Rationale:

• Native async/await support without ASGI adapters
• Built-in WebSocket support with no additional libraries
• Lower memory footprint than Django
• No ORM assumptions or admin interface overhead
• Direct control over request/response lifecycle

Why Dataset ORM Over SQLAlchemy

Rationale:

• Zero configuration required for basic operations
• Dictionary-based interface matches JSON API patterns
• Automatic table creation simplifies development
• Raw SQL available when needed for complex queries
• Significantly less boilerplate than SQLAlchemy models

Why Vanilla JavaScript Over React/Vue

Rationale:

• No build step required - direct browser execution
• No framework version upgrades or breaking changes
• Smaller payload - no framework runtime overhead
• Easier debugging - no virtual DOM abstraction
• Custom Elements provide component encapsulation
• Direct DOM access for performance-critical paths

Why SQLite as Default Database

Rationale:

• Zero configuration deployment - single file database
• No separate database server process required
• Excellent read performance for chat workloads
• Easy backup - copy a single file
• PostgreSQL available for high-write scenarios

Security Decisions

No IP Logging

Snek does not record IP addresses, request logs, or user behavior patterns. This is a fundamental privacy commitment, not a configuration option.

No Email Required

Email is optional. Users can register and participate without providing any personally identifiable information. Password recovery relies on administrator assistance.

Session Handling

Sessions use secure, HTTP-only cookies with server-side storage. Session data is encrypted and expires after configurable inactivity periods.

Password Storage

Passwords are hashed using SHA-256 with a configurable salt. The plain password is never stored or logged.

UI/UX Decisions

Dark Theme Default

The dark theme reduces eye strain for extended use, is preferred by developers, and provides better contrast for code display.

Card-Based Layouts

Content is organized in cards with consistent padding, border-radius, and shadow. Cards provide visual grouping and work well across screen sizes.

Minimal Animation

Animations are limited to subtle transitions (hover states, menu opens). No gratuitous motion that could distract or slow down interaction.

Typography

• Primary font: Segoe UI (system font stack fallback)
• Code font: Courier New (monospace)
• Base size: 16px with 1.5 line height
• Color palette: #eee (text), #7ef (links/accents), #0fa (secondary)

No Component Shadow DOM

Each component has its own CSS file that integrates with the global stylesheet. This allows consistent theming and easier debugging compared to Shadow DOM isolation.

Code Standards

No Comments

Code should be self-documenting through clear naming and structure. Comments indicate code that needs refactoring.

Author Attribution

Every file includes the author tag at the top:

Modular Organization

Code is organized into small, focused modules. One class per file for JavaScript. Related functionality grouped in directories.

Explicit Over Implicit

Prefer explicit code paths over magic behavior. No auto-imports, no implicit conversions, no hidden side effects.