From 2017f04541028d0a481af0699b26878c1aa6afeb Mon Sep 17 00:00:00 2001
From: Zeni Kim <zenik@smarteching.com>
Date: Sun, 13 Sep 2026 01:18:05 -0500
Subject: [PATCH] updated README.md

---
 README.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 73e7ccc..ec031bd 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,53 @@
 # Goffee Core 
 
-The core packages of Goffee framework
+The core library of the Goffee framework. It provides the building blocks used by every
+Goffee application: routing, the request `Context` and `Response`, hooks, events, JWT,
+sessions/cookies, cache, mailer, validation, templating, queues and the DB-backed scheduler.
+
+If you are going to develop an application, the way to do so is through the Cup project. Check out the [Goffee Cup repository](https://git.smarteching.com/goffee/cup).
+
+
+## Main concepts
+
+### App
+`core.App` is the application container. `core.New()` creates it, `Bootstrap()` initializes
+the logger, router and events manager, and `Run()` starts the HTTP server. Configuration is
+applied through the `Set...Config` methods (`SetRequestConfig`, `SetGormConfig`,
+`SetCacheConfig`, `SetEnvFileConfig`, ...).
+
+### Router and controllers
+Routes are registered on the singleton returned by `core.ResolveRouter()`. Each route maps
+a method + path to a `Controller` (a `func(*core.Context) *core.Response`) and an optional
+list of `Hook`s.
+
+```go
+router := core.ResolveRouter()
+router.Get("/users/:id", showUser, hooks.AuthCheck)
+```
+
+### Context and Response
+A `*core.Context` carries the request and exposes helpers: `GetRequestParam`, `GetPathParam`,
+`GetHeader`, `GetRequesBodyStruct`, `GetUploadedFile`, `MoveFile`, `CopyFile`,
+`MapToJson`, `CastToString`/`CastToInt`/`CastToFloat`, `GetBaseDirPath`, and service
+accessors like `GetLogger`, `GetGorm`, `GetCache`, `GetJWT`, `GetMailer`, `GetSession`,
+`GetQueueClient` and `GetEventsManager`. `c.Response` builds the reply with
+`Json`, `Text`, `HTML`, `Template`, `BufferFile`, `Redirect`, etc.
+
+## Packages
+
+| Package | Description |
+| --- | --- |
+| `core` | The framework itself: app, router, context, response, hooks, events, jwt, session, cache, mailer, validator, templates, queues and scheduler wiring. |
+| `core/env` | Helpers to read environment variables with defaults. |
+| `core/logger` | Logging drivers (`LogFileDriver`, `LogNullDriver`, ...). |
+| `core/scheduler` | The DB-backed task scheduler: `Store`, `QueueItem`, `ProcessedItem`, `SchedulerMeta`. |
+| `core/template/components` | Reusable template components (e.g. `PageCard`). |
+
+## Background processing
+- **Queues** (asynq): see `core.Queuemux` / `QueueConfig`.
+- **Scheduler**: a lightweight DB-backed runner with priorities, concurrent threads and a
+  global semaphore kill-switch. Use `core.Schedulermux` to register task handlers, then
+  `scheduler.NewStore(core.ResolveGorm())` and `SetStore` before `RunScheduler`.
+
+## License
+MIT-style license. See the [LICENSE](./LICENSE) file for details.