9 files changed,
190 insertions(+),
0 deletions(-)
Author:
Oleksandr Smirnov
olexsmir@gmail.com
Committed by:
GitHub
noreply@github.com
Committed at:
2025-09-25 13:54:45 +0300
Parent:
b3a528a
jump to
| M | .tool-versions |
| A | LICENSE |
| A | README.md |
| M | api/Taskfile.yml |
| A | docs/API.md |
| A | docs/Architecture.md |
| A | docs/CONTRIBUTING.md |
| A | docs/README.md |
| A | docs/screenshot.png |
A
LICENSE
··· 1 + GLWT(Good Luck With That) Public License 2 + Copyright (c) Everyone, except Author 3 + 4 +Everyone is permitted to copy, distribute, modify, merge, sell, publish, 5 +sublicense or whatever they want with this software but at their OWN RISK. 6 + 7 + Preamble 8 + 9 +The author has absolutely no clue what the code in this project does. 10 +It might just work or not, there is no third option. 11 + 12 + 13 + GOOD LUCK WITH THAT PUBLIC LICENSE 14 + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION, AND MODIFICATION 15 + 16 + 0. You just DO WHATEVER YOU WANT TO as long as you NEVER LEAVE A 17 +TRACE TO TRACK THE AUTHOR of the original product to blame for or hold 18 +responsible. 19 + 20 +IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 22 +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 23 +DEALINGS IN THE SOFTWARE. 24 + 25 +Good luck and Godspeed.
A
README.md
··· 1 +# Onasty 2 + 3 +Full-stack application for temporary note staring with automatic deletion after being read or upon expiration. 4 + 5 +<img src="./docs/screenshot.png" width=50% height=50%> 6 + 7 +## Features 8 +- 🔑 **Auth:** OAuth2 + JWT authentication. 9 +- 📧 **Account confirmation:** Email verification for new users. 10 +- 🔒 **Password protection:** Secure notes with a password. 11 +- 📝 **Custom slugs:** Choose your own note URL. 12 +- 👤 **Optional accounts:** Create an account to manage your notes, or use it anonymously. 13 +- 🚦 **Rate limiting:** Protects API from abuse. 14 +- ⏳ **Editable notes:** Change content or expiration time if the note hasn’t been read yet. 15 + 16 +## 📖 Usage 17 +1. Visit the frontend at `<your hosted url>`(there's no hosted app, yet). 18 +2. Create a note → get a unique link. 19 +3. Share the link — once opened, the note is gone. 20 + 21 +## 📚 Documentation 22 +Documentation on project and how to develop it lives [here](/docs)
A
docs/Architecture.md
··· 1 +# Architecture 2 + 3 +## Project structure 4 +```bash 5 +├── api/ # OpenAPI spec for the backend 6 +├── cmd/ 7 +│ ├── api # Entry point for the backend app 8 +│ └── seed # Entry point for the db seed app, useful during development 9 +├── deploy/ # All stuff related to deployment of this app 10 +├── docs/ # You're here, and reading the docs :D 11 +├── e2e/ # E2E tests for the API (go) 12 +├── go.mod 13 +├── go.sum 14 +├── infra/ # Configurations for infrastructure(grafana, loki, prometheus, caddy) 15 +├── internal/ # The core application (go) 16 +│ ├── config # > app config duh 17 +│ ├── dtos # > data transfer objects 18 +│ ├── events # > message publishing 19 +│ ├── hasher # > general interface to work with hash 20 +│ ├── jwtutil # > jwt token helpers 21 +│ ├── logger # > log/slog configuration 22 +│ ├── metrics # > Prometheus metrics 23 +│ ├── models # > domain entities 24 +│ ├── oauth # > interface to work with OAuth2 providers 25 +│ ├── service # > business logic (auth, notes, users 26 +│ ├── store # > persistence layer(postgres, redis) 27 +│ └── transport # > transport layer(http handlers) 28 +├── mailer/ # mailer service (go) 29 +├── migrations/ # DB migrations live here (sql) 30 +├── Taskfile.yml # task file with all tasks for the app development 31 +└── web/ # The frontend app (elm) 32 + ├── review # > elm-review configuration 33 + ├── static # > all static file(images, fonts, styles, etc) 34 + ├── src 35 + └── tests 36 +``` 37 + 38 +## Data flow 39 +1. Frontend/Api -> Backend 40 + - The Elm frontend ([web/](/web)) sends requests to the backend API. 41 +2. Transport layer (http handlers) 42 + - User provided data gets mapped into DTO and passed to service layer. 43 + - DTOs are only used between transport and services; the rest of the application uses domain models. 44 +3. Business logic (services) 45 + - Services receive DTOs, map them into domain models, and implement the use case (auth, notes, users). 46 + - Services may interact with: 47 + - Persistence (store → Postgres, Redis) 48 + - Events (events → NATS) 49 + - Utilities (`jwtutil`, `hasher`) 50 +4. Persistence 51 + - Postgres stores durable data (users, notes). 52 + - Redis handles caching/ephemeral state. 53 +5. Background tasks (fire-and-forget) 54 + - Some operations, like sending verification emails, are published as NATS events. 55 +6. Response 56 + - After business logic is complete, domain models are mapped back to DTOs, and returned via transport layer. 57 + - Elm frontend updates the UI accordingly. 58 +7. Observability 59 + - Services log via logger and export Prometheus metrics (`metrics`). 60 + - Grafana, Loki, and Prometheus provide monitoring. 61 + 62 +## Docker 63 +The project uses multiple Dockerfiles with a multi-stage build approach: 64 +- `builder.Dockerfile` – builds Go binaries and caches dependencies. 65 +- `runtime.Dockerfile` – lightweight Alpine base image with system packages preinstalled (used by app images to speed up builds). 66 +- `core.Dockerfile` – packages the main backend API service. 67 +- `mailer.Dockerfile` – packages the mailer service. 68 + 69 +## Services 70 +- Core service (go) 71 + - Exposes RestAPI (see. [API](/docs/API.md)) 72 + - Handles authentication 73 + - Manages notes life cycle 74 +- Mailer 75 + - Listens for events from the core. 76 + - Sends account confirmation and password reset emails. 77 + - Provides its own Prometheus metrics. 78 + - **NOTE:** all events of the service is documented [here](/mailer/) 79 + 80 +## Frontend 81 +- Built with [elm.land](https://elm.land) 82 +- Uses elm-review rules for consistency and quality. 83 +- Compiled into a static bundle (web/dist), served by Caddy.
A
docs/CONTRIBUTING.md
··· 1 +# Getting started 2 +First of, you need have [task](https://taskfile.dev), and [mise](https://mise.jdx.dev) installed. 3 + 4 +```bash 5 +git clone git@github.com:olexsmir/onasty.git 6 +cd onasty 7 +mise use # installs required tools for development 8 +task api:install # installs deps to work with openapi 9 +task web:install # installs all node_modules for the frontend gods 10 +task docker:up # starts all docker containers 11 +task frontend:dev # starts dev server for elm app 12 +task run # recompiled and restart core and mailer services 13 +``` 14 + 15 +# Code Structure Guidelines 16 +See [Architecture](./Architecture). 17 + 18 +# Testing 19 +```bash 20 +task test # runs all tests in the project 21 + # > backend e2e and units 22 + # > frontend units 23 +task test:unit # backend unit tests 24 +task test:e2e # backend e2e tests 25 +task frontend:test # frontend unit tests 26 +``` 27 + 28 +# Coding Style & Linting 29 +- For general editor config [editorconfig](https://editorconfig.org/) is used 30 +- Go 31 + - `gofumpt`, `goimports`, `golines` are used for formatting 32 + - `golangci-lint` is used for linting 33 +- Elm 34 + - `elm-format` is used for formatting 35 + - `elm-review` is used for linting 36 + 37 +# Adding Features 38 +1. Make sure there’s no duplicate functionality. 39 +1. Add new endpoints to `api/openapi.yml` if needed. 40 +1. Add unit tests or e2e tests as appropriate. 41 +1. For new mailer events: add event struct in `internal/events` and corresponding handler in `mailer/`. 42 + 43 +# Branching & Workflow 44 +- Use feature branches for any changes: `feat/<description>` or `fix/<escription>`. 45 +- Follow [Conventional commit](https://www.conventionalcommits.org/en/v1.0.0) messages. 46 +- Open PR against `main` branch.
A
docs/README.md
··· 1 +# Docs 2 +- [Project structure](./Architecture.md) 3 +- [Development](./CONTRIBUTING.md) 4 +- [API](./API.md)
