Developer
Architecture
Internal engineering, directory organization, and high-performance design patterns.
Architecture
GO Shortener is engineered in modern Go (1.22+) using a modular, decoupled architecture tailored specifically for high throughput and negligible resource consumption.
High-Level Architectural Diagram
+-------------------------------------------------------------+
| HTTP Requests (Port 3000) |
+-------------------------------------------------------------+
|
v
+-------------------------------------------------------------+
| HTTP Middleware Pipeline |
| - Security Headers (HSTS, CSP, X-Frame-Options) |
| - Session Authenticator (go_session Cookie / JWT) |
| - Rate Limiter & Identity Hash Provider |
| - Intrusion Detection & Audit Logger |
+-------------------------------------------------------------+
|
+---------------+---------------+
| |
v v
+-----------------------------+ +-----------------------------+
| API Handlers Layer | | Embedded Frontend Static |
| (/api/links, /api/auth, | | Handler (embed.FS) |
| /api/user, /api/admin) | | (HTML, CSS, JS, Favicon) |
+-----------------------------+ +-----------------------------+
|
v
+-------------------------------------------------------------+
| Business Service Layer |
| - SSRF & Protocol Validator |
| - Quota Engine (15/24h anon, 100/mo registered) |
| - Expiration & Code Renewal Calculator |
| - Telemetry Anonymizer (SHA-256 IP Hashing) |
+-------------------------------------------------------------+
|
+---------------+---------------+
| |
v v
+-----------------------------+ +-----------------------------+
| Repository Layer | | External Clients |
| (SQLite CRUD Ops) | | - Cloudflare Turnstile API |
+-----------------------------+ | - Firebase Auth Verifier |
| +-----------------------------+
v
+-------------------------------------------------------------+
| Pure Go SQLite Engine |
| - modernc.org/sqlite (CGO-Free) |
| - Single-Writer Concurrency (MaxOpenConns = 1) |
| - Write-Ahead Logging (WAL Mode) |
+-------------------------------------------------------------+
Directory Organization
The codebase follows idiomatic Go standards:
backend/
├── cmd/
│ └── server/
│ └── main.go # Application entrypoint & HTTP router wiring
├── internal/
│ ├── config/ # Environment variable loading & defaults
│ ├── database/ # SQLite connection pool, pragmas, & auto-migration
│ ├── embedded/ # embed.FS packaging of the static frontend
│ ├── handlers/ # REST API endpoints & HTTP request parsing
│ ├── middleware/ # Security headers, auth cookies, & rate limiters
│ ├── models/ # Struct definitions for links, users, & analytics
│ ├── repository/ # SQL queries, parameter binding, & transactions
│ ├── service/ # Domain logic (SSRF checks, quota calculations)
│ └── validator/ # Input validation, URL format, & scheme checks
├── pkg/ # Reusable utilities (hashing, random code generation)
├── go.mod # Go module definition
└── go.sum # Dependency checksum verification
Key Design Patterns
1. 100% Standalone Executable (embed.FS)
All HTML templates, vanilla JavaScript controllers, stylesheets, and icons residing in frontend/public are baked into the Go binary at compile time via Go's native //go:embed all:public.
- Eliminates filesystem read errors on deployment.
- Assets are served directly from RAM with proper
ETagandCache-Controlheaders. - Total binary size is ~13 MB.
2. CGO-Free SQLite WAL Concurrency
Traditional Go SQLite wrappers require a C compiler (gcc), preventing cross-compilation. GO Shortener utilizes modernc.org/sqlite, a 100% pure Go SQLite transpilation:
- Single-Writer Lock: Set via
db.SetMaxOpenConns(1)to eliminate database lock contention (database is locked). - WAL Mode (
PRAGMA journal_mode=WAL;): Allows simultaneous non-blocking concurrent readers while a write transaction is in progress. - Busy Timeout (
PRAGMA busy_timeout=5000;): Automatically retries pending writes for up to 5 seconds if a transaction is waiting.