{"id":49555757,"url":"https://github.com/boutaj/raqym","last_synced_at":"2026-05-03T02:02:54.344Z","repository":{"id":353633547,"uuid":"1118520604","full_name":"boutaj/raqym","owner":"boutaj","description":"Arabic-first productivity backend built with Go, PostgreSQL, JWT auth, and role-based access control","archived":false,"fork":false,"pushed_at":"2026-05-02T23:03:25.000Z","size":577,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T23:30:22.953Z","etag":null,"topics":["chi","docker","go","jwt","postgresql"],"latest_commit_sha":null,"homepage":"https://raqym.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boutaj.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":null,"dco":null,"cla":null}},"created_at":"2025-12-17T22:07:16.000Z","updated_at":"2026-05-02T23:03:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/boutaj/raqym","commit_stats":null,"previous_names":["boutaj/raqym"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/boutaj/raqym","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boutaj%2Fraqym","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boutaj%2Fraqym/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boutaj%2Fraqym/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boutaj%2Fraqym/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boutaj","download_url":"https://codeload.github.com/boutaj/raqym/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boutaj%2Fraqym/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32555839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T00:31:16.350Z","status":"online","status_checked_at":"2026-05-03T02:00:09.297Z","response_time":103,"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":["chi","docker","go","jwt","postgresql"],"created_at":"2026-05-03T02:02:53.294Z","updated_at":"2026-05-03T02:02:54.330Z","avatar_url":"https://github.com/boutaj.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Raqym\n\nRaqym is a Go-based task management API built for Arabic-first productivity workflows. It focuses on the backend foundations of a real product: authentication, account activation, role-aware access control, task and list management, pagination, filtering, and API documentation.\nIt includes layered architecture, transactional user onboarding, JWT-based authentication, SMTP-backed email flows, SQL migrations, and a documented HTTP API.\n\n## Core Features\n\n- User registration with password hashing\n- Email-based account activation flow\n- JWT authentication for protected endpoints\n- Basic auth protection for internal tooling endpoints\n- Fixed-window rate limiting for API traffic\n- Optional Redis-backed user caching\n- List creation and management\n- Task creation, retrieval, update, delete, search, and pagination\n- Role-aware access checks\n- Graceful shutdown on interrupt/termination signals\n- Swagger/OpenAPI documentation\n\n## Tech Stack\n\n- Language: Go\n- Router: `chi`\n- Database: PostgreSQL\n- Migrations: `golang-migrate`\n- Auth: JWT\n- Password hashing: Argon2id\n- Mail: SMTP\n- Cache / in-memory store: Redis\n- Rate limiting: custom fixed-window limiter\n- Logging: `zap`\n- API docs: `swaggo`\n- Local services: Docker Compose, PostgreSQL, Redis\n\n## Architecture\n\nThe codebase follows a pragmatic layered structure:\n\n- `cmd/api`\n  HTTP entrypoint, route registration, middleware, handlers, and response helpers.\n- `internal/repository`\n  Data access layer for users, roles, tasks, lists, and pagination queries.\n- `internal/repository/cache`\n  Redis-backed cache storage for frequently accessed user records.\n- `internal/auth`\n  JWT generation and validation.\n- `internal/mailer`\n  SMTP client and email templates for invitation and activation flows.\n- `internal/ratelimiter`\n  Fixed-window rate limiter used by API middleware.\n- `internal/db`\n  Database connection setup and seed support.\n- `internal/env`\n  Environment variable loading helpers.\n- `cmd/migrate`\n  SQL migrations and seed entrypoints.\n- `scripts`\n  First-time database initialization SQL.\n- `docs`\n  Generated Swagger artifacts.\n\n## API Highlights\n\nThe API is versioned under `/v1` and includes routes for:\n\n- `GET /healthz`\n  Basic-auth protected health check.\n- `GET /docs/*`\n  Basic-auth protected Swagger UI and OpenAPI documentation.\n- `POST /authentication/user`\n  Register a user and trigger the activation flow.\n- `PUT /users/activate/{token}`\n  Activate an invited user account.\n- `POST /authentication/token`\n  Exchange credentials for a JWT.\n- `GET /users/me`\n  Retrieve the authenticated user profile.\n- `GET /tasks`\n  List tasks with pagination, priority filtering, search, and sorting.\n- `POST /tasks`\n  Create a task.\n- `GET /tasks/{taskID}`\n  Fetch a single task.\n- `PATCH /tasks/{taskID}`\n  Update a task.\n- `DELETE /tasks/{taskID}`\n  Delete a task.\n- `POST /lists`\n  Create a list.\n- `GET /lists/{listID}`\n  Fetch a single list.\n- `PATCH /lists/{listID}`\n  Update a list.\n- `DELETE /lists/{listID}`\n  Delete a list.\n\nSwagger UI is exposed through the docs route when the API is running. Use the configured Basic Auth credentials to access `/v1/healthz` and `/v1/docs/*`.\n\n## Local Setup\n\n### Prerequisites\n\n- Go installed locally\n- Docker and Docker Compose\n- PostgreSQL migration CLI if you want to run migrations manually via `make`\n- Air if you want live reload while developing\n\n### 1. Start Local Services\n\n```bash\ndocker compose up -d\n```\n\nThis starts the local PostgreSQL and Redis containers used for development.\n\n### 2. Configure Environment Variables\n\nCreate an `.env` file in the project root with values for the server, database, auth, and SMTP settings used by the app.\n\nTypical variables used by this project include:\n\n```env\nSERVER_ADDR=localhost:8080\nFRONTEND_URL=http://localhost:4000\nENV=development\n\nDATABASE_ADDR=postgres://user:password@localhost:5432/taskmanager?sslmode=disable\nDATABASE_MAX_OPEN_CONS=30\nDATABASE_MAX_IDLE_CONS=30\nDATABASE_MAX_IDLE_TIME=15m\n\nREDIS_ADDR=0.0.0.0:6379\nREDIS_PW=\nREDIS_DB=0\nREDIS_ENABLED=true\n\nAUTH_BASIC_USER=admin\nAUTH_BASIC_PASS=admin\nJWT_AUTH_SECRET=change-me\nAPP_NAME=taskmanager\n\nSMTP_FROMEMAIL=admin@raqym.com\nSMTP_HOST=localhost\nSMTP_PORT=25\nSMTP_USERNAME=\nSMTP_PASSWORD=\n\nPOSTGRES_DB=taskmanager\nPOSTGRES_USER=user\nPOSTGRES_PASSWORD=password\n\nRATELIMITER_REQ_COUNT=20\nRATELIMITER_EN=true\n```\n\n### 3. Initialize the Database\n\nIf the `taskmanager` database does not already exist, run the first-time setup SQL before migrations:\n\n```bash\ndocker compose exec -T db psql -U user -d postgres \u003c scripts/db_init.sql\n```\n\nIf you are using the included Docker Compose setup from a fresh volume, PostgreSQL may already create the database from `POSTGRES_DB=taskmanager`, so you can skip this step when the database already exists.\n\n### 4. Run Migrations\n\n```bash\nmake migrate-up\n```\n\n### 5. Seed Data\n\n```bash\nmake seed\n```\n\n### 6. Run the API\n\nFor development with live reload, install Air if you do not already have it:\n\n```bash\ngo install github.com/air-verse/air@latest\n```\n\nThen run the API with:\n\n```bash\nair\n```\n\nIf you do not want to install Air, you can run the API directly with Go:\n\n```bash\ngo run ./cmd/api\n```\n\n## Useful Commands\n\n```bash\nmake db-connect      # Connect to the PostgreSQL CLI\nmake redis-connect   # Connect to the Redis CLI\ndocker compose exec -T db psql -U user -d postgres \u003c scripts/db_init.sql\n# Run the db_init.sql file in the PostgreSQL CLI\nmake migrate-up      # Run migrations\nmake migrate-down    # Roll back migrations\nmake seed            # Seed the database with data\nmake test            # Test the endpoints\nair                  # Run the Go live-reloading tool\n```\n\n## Engineering Notes\n\nSome decisions in this codebase were made to reflect backend engineering concerns beyond basic endpoint wiring:\n\n- Middleware-driven auth to keep handlers focused on business logic\n- Repository layer to isolate SQL from transport concerns\n- Transactional user creation plus invitation persistence\n- SAGA-style compensation flow when user creation succeeds but email delivery fails\n- Validation at the request boundary\n- Structured logging for operational visibility\n- Redis-backed caching for authenticated user lookup when Redis is enabled\n- Fixed-window rate limiting with `Retry-After` responses\n- Graceful shutdown on `SIGINT` and `SIGTERM`\n- Swagger annotations to keep the API explorable for reviewers and collaborators\n\n## What I’d Build Next\n\n- [ ] Refresh tokens and token revocation\n- [ ] Better authorization policies for shared or admin-managed resources\n- [ ] Broader test coverage for handlers and repository logic\n- [ ] Background job processing for email delivery\n- [x] Add API user authentication and activation handler tests\n- [x] Implement graceful shutdown for the HTTP server and background resources\n- [x] Add Redis caching for authenticated user lookup\n- [x] Add rate limiting to protect authentication and public-facing endpoints\n- [ ] Expose server metrics for monitoring and observability\n- [ ] Set up CI/CD pipelines for linting, testing, and deployment\n- [ ] Deploy the application on AWS\n- [ ] Frontend client for the Arabic-first product experience\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboutaj%2Fraqym","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboutaj%2Fraqym","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboutaj%2Fraqym/lists"}