{"id":31975405,"url":"https://github.com/dmitrymomot/foundation","last_synced_at":"2025-10-14T20:40:05.951Z","repository":{"id":312093038,"uuid":"1038183855","full_name":"dmitrymomot/foundation","owner":"dmitrymomot","description":"Opinionated Go web framework with type-safe handlers, middleware, sessions, validation, and database/storage integrations","archived":false,"fork":false,"pushed_at":"2025-10-04T06:46:34.000Z","size":1666,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T07:07:53.080Z","etag":null,"topics":["framework","go-router","golang","router","toolkit"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmitrymomot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-14T18:56:02.000Z","updated_at":"2025-10-03T04:44:07.000Z","dependencies_parsed_at":"2025-08-28T20:42:36.440Z","dependency_job_id":"c6961875-0a19-4002-9ac4-23941d8dbc61","html_url":"https://github.com/dmitrymomot/foundation","commit_stats":null,"previous_names":["dmitrymomot/foundation"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/dmitrymomot/foundation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitrymomot%2Ffoundation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitrymomot%2Ffoundation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitrymomot%2Ffoundation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitrymomot%2Ffoundation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmitrymomot","download_url":"https://codeload.github.com/dmitrymomot/foundation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitrymomot%2Ffoundation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279020891,"owners_count":26086949,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framework","go-router","golang","router","toolkit"],"created_at":"2025-10-14T20:39:56.642Z","updated_at":"2025-10-14T20:40:05.937Z","avatar_url":"https://github.com/dmitrymomot.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# foundation\n\nA comprehensive toolkit for building secure, scalable web applications in Go. The library implements modern patterns including generics for type safety, functional options for configuration, and interface-based design for flexibility and testability.\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dmitrymomot/foundation)\n[![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/dmitrymomot/foundation)](https://github.com/dmitrymomot/foundation/tags)\n[![Go Reference](https://pkg.go.dev/badge/github.com/dmitrymomot/foundation.svg)](https://pkg.go.dev/github.com/dmitrymomot/foundation)\n[![License](https://img.shields.io/github/license/dmitrymomot/foundation)](https://github.com/dmitrymomot/foundation/blob/main/LICENSE)\n\n[![Tests](https://github.com/dmitrymomot/foundation/actions/workflows/tests.yml/badge.svg)](https://github.com/dmitrymomot/foundation/actions/workflows/tests.yml)\n[![CodeQL Analysis](https://github.com/dmitrymomot/foundation/actions/workflows/codeql.yml/badge.svg)](https://github.com/dmitrymomot/foundation/actions/workflows/codeql.yml)\n[![GolangCI Lint](https://github.com/dmitrymomot/foundation/actions/workflows/golangci-lint.yml/badge.svg)](https://github.com/dmitrymomot/foundation/actions/workflows/golangci-lint.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/dmitrymomot/foundation)](https://goreportcard.com/report/github.com/dmitrymomot/foundation)\n\n## Installation\n\n```bash\ngo get github.com/dmitrymomot/foundation\n```\n\n## Why Foundation Exists\n\nAfter building multiple Go web applications, I got tired of doing the same work over and over - copy-pasting request handlers between projects, creating huge boilerplate files to work around framework limitations, reimplementing session management for the third time. Each new project meant another week of setup before writing actual business logic.\n\nFoundation is my solution: all the repetitive code I kept rewriting, collected into reusable packages. It's designed to speed up my own project delivery by providing the pieces I always need - type-safe routing with generics, session management, request validation, background jobs - without the ceremony.\n\nNo framework lock-in, no magic. Just composable packages that solve common problems so I can focus on building features instead of reinventing infrastructure.\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"database/sql\"\n\t\"log\"\n\n\t\"github.com/dmitrymomot/foundation/core/handler\"\n\t\"github.com/dmitrymomot/foundation/core/response\"\n\t\"github.com/dmitrymomot/foundation/core/router\"\n\t\"github.com/dmitrymomot/foundation/core/server\"\n\t\"github.com/dmitrymomot/foundation/middleware\"\n)\n\n// Define your custom context with exactly what you need\ntype AppContext struct {\n\t*router.Context\n\tDB       *sql.DB\n\tUserID   string\n\tTenantID string\n}\n\nfunc main() {\n\tr := router.New[*AppContext]()\n\n\t// Add middleware\n\tr.Use(middleware.CORS[*AppContext]())\n\tr.Use(middleware.RequestID[*AppContext]())\n\tr.Use(middleware.Logging[*AppContext]())\n\n\t// Type-safe handlers - no casting needed\n\tr.Get(\"/\", func(ctx *AppContext) handler.Response {\n\t\treturn response.JSON(map[string]string{\n\t\t\t\"status\":   \"ok\",\n\t\t\t\"user_id\":  ctx.UserID,\n\t\t\t\"tenant\":   ctx.TenantID,\n\t\t})\n\t})\n\n\tr.Get(\"/users/{id}\", func(ctx *AppContext) handler.Response {\n\t\tuserID := ctx.Param(\"id\")\n\t\t// ctx.DB is available with full type safety\n\t\treturn response.JSON(map[string]string{\n\t\t\t\"user_id\": userID,\n\t\t\t\"message\": \"User found\",\n\t\t})\n\t})\n\n\t// Create and run server with graceful shutdown\n\tctx := context.Background()\n\tif err := server.Run(ctx, \":8080\", r); err != nil {\n\t\tlog.Fatal(err)\n\t}\n}\n```\n\n## Common Patterns\n\n**Multi-tenant SaaS**: Session management with tenant isolation, rate limiting per tenant, JWT authentication with tenant claims\n**Background Processing**: Queue jobs, schedule tasks, process webhooks with retries, CQRS command/event patterns\n**Security**: Input sanitization, TOTP 2FA, AES encryption, secure token generation, device fingerprinting\n**Observability**: Structured logging with slog, request ID tracking, health check endpoints\n\n## Features\n\nThe foundation library is organized into four main categories, providing everything needed to build production-ready web applications:\n\n### Core Framework (22 packages)\n\n**Request \u0026 Response**\n\n- HTTP request data binding with validation (`core/binder`)\n- Multiple response formats: JSON, HTML, SSE, WebSocket (`core/response`)\n- Secure cookie management with encryption (`core/cookie`)\n- Type-safe handler abstractions with generics (`core/handler`)\n\n**Routing \u0026 Server**\n\n- High-performance HTTP router with middleware support (`core/router`)\n- HTTP server with graceful shutdown (`core/server`)\n- Static file serving with SPA support (`core/static`)\n- Let's Encrypt certificate management (`core/letsencrypt`)\n\n**State Management**\n\n- Generic session system with pluggable transports (`core/session`, `core/sessiontransport`)\n- Thread-safe LRU cache implementation (`core/cache`)\n- Local filesystem storage with security features (`core/storage`)\n\n**Background Work \u0026 Architecture**\n\n- Job queue system with workers and scheduling (`core/queue`)\n- CQRS command pattern with handlers and message bus (`core/command`)\n- Event-driven architecture with type-safe handlers (`core/event`)\n\n**Security \u0026 Validation**\n\n- Input sanitization and data cleaning (`core/sanitizer`)\n- Rule-based data validation system (`core/validator`)\n\n**Operations \u0026 Configuration**\n\n- Type-safe environment variable loading (`core/config`)\n- Structured logging built on slog (`core/logger`)\n- Health monitoring endpoints (`core/health`)\n- Internationalization with CLDR plural rules (`core/i18n`)\n- Email sending interface with template support (`core/email`)\n\n### HTTP Middleware\n\nPre-built middleware components for common cross-cutting concerns:\n\n- **Security**: CORS, JWT authentication, security headers\n- **Observability**: Request logging, request ID tracking\n- **Performance**: Rate limiting, request timeout handling\n- **Development**: Debug utilities, request/response debugging\n\n### Utilities (16 packages)\n\nStandalone packages providing specific functionality:\n\n- **Security**: JWT tokens (`pkg/jwt`), TOTP authentication (`pkg/totp`), AES encryption (`pkg/secrets`), secure token generation (`pkg/token`)\n- **Rate Limiting**: Token bucket implementation with pluggable storage (`pkg/ratelimiter`)\n- **Async Programming**: Future pattern utilities (`pkg/async`)\n- **Communication**: Pub/sub messaging system (`pkg/broadcast`), webhook delivery with retries (`pkg/webhook`)\n- **AI \u0026 ML**: Text to vector embeddings using OpenAI and Google AI (`pkg/vectorizer`)\n- **Web Utilities**: Client IP extraction (`pkg/clientip`), User-Agent parsing (`pkg/useragent`), device fingerprinting (`pkg/fingerprint`)\n- **Content Generation**: QR code generation (`pkg/qrcode`), URL-safe slugs (`pkg/slug`), random name generation (`pkg/randomname`)\n- **Feature Management**: Feature flagging with rollout strategies (`pkg/feature`)\n\n### Integrations (7 packages)\n\nProduction-ready integrations for databases, email services, and storage:\n\n- **Databases**: PostgreSQL with migrations and connection pooling (`integration/database/pg`), MongoDB with health checking (`integration/database/mongo`), Redis with retry logic (`integration/database/redis`), OpenSearch client (`integration/database/opensearch`)\n- **Email Services**: Postmark API integration (`integration/email/postmark`), SMTP sending (`integration/email/smtp`)\n- **Storage**: S3-compatible object storage (`integration/storage/s3`)\n\n## Architecture Patterns\n\nThe foundation library follows these key architectural patterns:\n\n- **Generics for type safety**: Custom context types eliminate runtime type assertions\n- **Functional options**: Flexible configuration without breaking changes\n- **Interface-based design**: Pluggable implementations for testing and modularity\n- **Security-first approach**: Built-in sanitization, validation, and encryption\n- **Multi-tenant considerations**: Tenant isolation patterns throughout the design\n\n## Documentation\n\nFor detailed documentation on any package, use the go doc command:\n\n```bash\ngo doc github.com/dmitrymomot/foundation/core/binder\ngo doc -all github.com/dmitrymomot/foundation/middleware\n```\n\nEach package contains comprehensive documentation with usage examples and detailed API references.\n\n## Requirements\n\n- Go 1.24 or later\n\n## Status\n\nActive development with breaking changes allowed as we work towards v1.0. Production use is at your own discretion - API stability not yet guaranteed.\n\n## License\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text.\n\n## Contributing\n\nContributions are welcome! This is an actively developed library, and breaking changes are allowed as we work towards a stable API.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmitrymomot%2Ffoundation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmitrymomot%2Ffoundation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmitrymomot%2Ffoundation/lists"}