1# Dumb Browser Constitution
2
3## Core Principles
4
5### I. Speed First (NON-NEGOTIABLE)
6- Fast startup time is paramount - no feature worth compromising speed
7- Single binary with embedded assets - no external dependencies at runtime
8- WebKit2GTK for rendering - full compliance without reinventing wheels
9- Minimal UI overhead - focus on web content, not chrome
10
11### II. Universal Launcher Compatibility
12- Support any dmenu-compatible launcher (fuzzel, rofi, tofi, wofi, bemenu)
13- Standard stdin/stdout protocol - no launcher-specific integrations
14- Clean text-based format for history/suggestions
15- Pipeline-friendly: `dumb-browser --dmenu | launcher | dumb-browser --dmenu`
16
17### III. Smart URL Handling
18- Direct URL detection: `reddit.com` → navigate directly
19- Search shortcuts: `g: golang tutorial` → Google search  
20- History-first search: `reddit` → check history before web search
21- No ambiguity - clear rules for input interpretation
22
23### IV. Privacy-Conscious History
24- Local SQLite database only - no cloud sync
25- Configurable retention periods and cleanup
26- Visit counting for intelligent suggestions
27- User controls data - easy to clear/export
28
29### V. Wayland Native
30- Built for modern Linux desktop - sway, hyprland, etc.
31- WebKit2GTK provides native Wayland integration
32- Single instance handling for launcher integration
33- Minimal resource usage - no background services
34
35## Technical Standards
36
37### Stack Requirements
38- **Backend**: Go + Wails([v3-alpha](https://github.com/wailsapp/wails/tree/v3.0.0-alpha.28)) + WebKit2GTK + SQLite
39- **CLI**: Cobra + Viper for configuration
40- **Database**: SQLC for type-safe SQL generation
41- **Validation**: Input sanitization libraries ([go-playground/validator](https://github.com/go-playground/validator))
42- **Build**: Single static binary with embedded frontend
43- **Dependencies**: WebKit2GTK + GTK3 only (system packages)
44
45### Performance Targets
46- Startup time: < 500ms from cold start
47- Memory usage: < 100MB baseline + WebKit overhead
48- History search: < 50ms for 1000+ entries
49- Single instance lock: < 10ms response time
50
51### Quality Gates
52- All database queries must use SQLC generated code
53- All user input must be validated and sanitized
54- Error handling: proper Go error chains, no panics in user paths 
55- Logging: structured logging for debugging, minimal in production (Slog for logging in text mode)
56
57## Development Workflow
58
59### Implementation Order
601. Core CLI structure (Cobra + Viper)
612. Database schema + SQLC integration
623. URL parser + search engine logic with fuzzy finder algorithm
634. History management (CRUD operations)
645. Wails browser integration
656. Dmenu compatibility layer
667. Configuration system
67
68### Testing Requirements
69- Unit tests for URL parsing logic
70- Integration tests for database operations
71- Manual testing with fuzzel integration
72- Cross-launcher compatibility verification
73
74## Constraints
75
76### Simplicity Mandate
77- KISS principle - no over-engineering
78- Clean Code philosophy throughout
79- Single responsibility per module
80- Minimal configuration surface
81
82### Security Requirements
83- No credential storage or session management
84- Input sanitization for all user data
85- SQL injection prevention via SQLC
86- No network requests except web browsing
87
88## Governance
89
90This constitution defines the project's core identity and technical direction. All implementation decisions must align with these principles, prioritizing speed and simplicity above feature richness.
91
92**Version**: 1.0.0 | **Ratified**: 2025-01-09 | **Last Amended**: 2025-01-09