From ba426f1cb095c2248e7e7c2480bef1d04006a4e5 Mon Sep 17 00:00:00 2001 From: Ivan Skvortsov Date: Mon, 9 Jun 2025 19:05:10 +0300 Subject: [PATCH 1/4] docs: improved README and .env.example --- .env.example | 68 ++++++++++++++++++++++++++++++++++++++++------------ README.md | 38 ++++++++++++++--------------- 2 files changed, 72 insertions(+), 34 deletions(-) diff --git a/.env.example b/.env.example index e6d8532..2d016a7 100644 --- a/.env.example +++ b/.env.example @@ -1,31 +1,69 @@ -# Backend -ENV=dev # dev | prod | demo +# ======================== +# Backend Configuration +# ======================== + +# Set the environment mode: +# - dev: Enables development features like database reset and seeding +# - prod: Production mode +# - demo: Public demo mode with single-user mode and restricted functionality +ENV=dev + +# Leave this unchanged if you're using docker-compose DATABASE_URL=postgresql+psycopg2://evsy:evsy@db:5432/evsy + +# Public URL of the frontend (used for CORS policy and redirects) +# For local dev use http://localhost:3000 FRONTEND_URL=http://localhost:3000 -# Frontend -VITE_ENV=dev # dev | prod | demo +# ======================== +# Frontend Configuration +# ======================== + +# Should match the ENV variable above +VITE_ENV=dev + +# Base URL of the backend API +# For local dev use http://localhost:8000/api/v1 VITE_API_URL=http://localhost:8000/api/v1 + +# Logging verbosity in browser console (e.g., debug, info, warn, error) VITE_LOG_LEVEL=error + +# If deploying behind a reverse proxy, add your public domain here __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS=demo.evsy.dev -# Auth +# ======================== +# Auth Configuration +# ======================== -## Secret key for signing JWTs. Use a secure 32+ character string. +# Secret key used to sign JWTs. Must be a secure 32+ char string. SECRET_KEY=YOUR_32_CHAR_SECRET_KEY -## GitHub OAuth credentials -## Create your app here: https://github.com/settings/developers -## Set "Authorization callback URL" to: -## http://localhost:8000/api/v1/auth/oauth/callback +# === GitHub OAuth === +# If provided, GitHub OAuth login will be enabled +# Create your app here: https://github.com/settings/developers +# Set the authorization callback URL to +# /api/v1/auth/oauth/callback GITHUB_CLIENT_ID= GITHUB_CLIENT_SECRET= -## Google OAuth credentials -## Create credentials here: https://console.cloud.google.com/apis/credentials -## Set "Authorized redirect URI" to: -## http://localhost:8000/api/v1/auth/oauth/callback +# === Google OAuth === +# If provided, Google OAuth login will be enabled +# Create credentials here: https://github.com/settings/developers +# Set the authorized redirect URI to +# /api/v1/auth/oauth/callback GOOGLE_CLIENT_ID= -GOOGLE_CLIENT_SECRET= \ No newline at end of file +GOOGLE_CLIENT_SECRET= + + +# ======================== +# Reverse Proxy Notes +# ======================== + +# We recommend to deploy both backend and frontend on the same domain, +# with backend served under /api. For example: +# +# - https://yourdomain.com → frontend (port 3000) +# - https://yourdomain.com/api → backend (port 8000) diff --git a/README.md b/README.md index fb62bda..44fed94 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,28 @@ # Evsy Evsy is a lightweight admin panel for managing and documenting product analytics events and their properties. -(!) Evsy is currently in active development. Expect rapid improvements and frequent updates! - ![Evsy main page screenshot.](screenshot.png) -## ✨ About -Evsy is an open-source application for managing analytics events — including event descriptions, their attributes (fields), and tags. +Check out the live demo at [demo.evsy.dev](demo.evsy.dev) +- Login: `demo@evsy.dev` +- Password: `bestructured` -It helps product teams, analysts, and developers structure and document their events in a convenient, extensible way. +## ✨ About +Evsy is an open-source application that helps product teams, analysts, and developers structure, document, and maintain a single source of truth for product analytics events and fields. ## 📚 Features - Create and document events and fields. -- Organize them by type, tag, or team. -- Export events to Swagger schemas. -- Sign up via email/password or OAuth2 (GitHub & Google) +- Organize by type, tag, or team. +- Export events as Swagger-compatible schemas. +- Sign in with email/password or OAuth2 (GitHub & Google). + **Future roadmap includes:** -- Roles and user management; -- Audit log (history of changes) and event versioning; +- Role-based access control (RBAC); +- History of changes and event versioning; - Full-text search; -- Additional event states (`draft`, `archived`); -- Markdown descriptions; -- Grafana integration; +- Draft and archived states for events; +- Markdown-based descriptions; - ... and more! ## 🚀 Quick Start @@ -30,21 +30,21 @@ To run Evsy via Docker compose, do: 1. `cp .env.example .env` 2. `make up` -### Alternative: deploy to Render -[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/ivanskv2000/evsy) +> Make sure to review .env.example — it contains helpful comments for configuring your setup. ## ⚙️ Tech Stack - Backend: FastAPI + Pydantic + SQLAlchemy + Alembic -- Frontend: Vue 3 + Vite + Shadcn +- Frontend: Vue 3 + Vite +- Component library: [shadcn-vue](https://www.shadcn-vue.com/) ## 🧩 Project Structure -Evsy is a project combining a Python backend and a modern JS frontend, developed and versioned together. +Evsy is a project combining a Python FastAPI backend and a Vue3 frontend, developed and versioned together. ``` evsy/ -├── backend/ # FastAPI backend (Python, Poetry-managed) +├── backend/ # FastAPI backend (Poetry-managed) │ ├── app/ # Application code -│ └── tests/ # Pytest test suite +│ └── tests/ # Pytest ├── frontend/ # Vue 3 + Vite frontend (npm-managed) │ ├── src/ # Application code │ └── public/ # Static assets From b18a80366ca5408384dc58aa908643285f3ee389 Mon Sep 17 00:00:00 2001 From: Ivan Skvortsov Date: Mon, 9 Jun 2025 19:30:18 +0300 Subject: [PATCH 2/4] docs: improved CONTRIBUTING.md --- CONTRIBUTING.md | 60 +++++++++++++++++++++++++++++++++++++------------ README.md | 2 +- 2 files changed, 47 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0801e7c..afe4399 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,21 +5,54 @@ We deeply appreciate every bit of help, whether it's fixing a bug, suggesting an ## 🫶 You don’t have to code to contribute -We welcome all kinds of contributions: +Not a developer? No problem — Evsy welcomes all kinds of contributions: -- 🐛 **Bug reports** — Found something broken? Let us know! -- 💡 **Feature suggestions** — Got an idea to improve Evsy? -- 🎨 **Design help** — We love thoughtful UI/UX suggestions. -- 📚 **Docs feedback** — Is something unclear? Missing? Tell us. -- 🙏 Just saying “this helped” — Encouragement matters, too. +- Report bugs — If something’s not working as expected, let us know. +- Suggest features — Ideas to improve workflows or usability are always appreciated. +- Give design feedback — UI/UX suggestions help us make Evsy more intuitive. +- Improve the docs — Flag anything confusing or missing. +- Share your experience — Even a quick "this was helpful" can go a long way. -Create an [issue](https://github.com/ivanskv2000/evsy/issues) or open a [discussion](https://github.com/ivanskv2000/evsy/discussions) — we’d love to hear from you. +You can open an [issue](https://github.com/ivanskv2000/evsy/issues) — we’d love to hear from you. ---- -## 🧑‍💻 If you do want to contribute code +## 🧑‍💻 Contributing code -### Backend (FastAPI, Poetry) +### Docker-compose setup (recommended) + +You can setup both the backend and frontend in dev mode with hot-reloading: + +```bash +make dev +``` + +This launches everything via `docker-compose.dev.yaml`: + +- FastAPI backend on `localhost:8000` +- Vite frontend on `localhost:3000` + + +When you need to create a new migration: + +```bash +make revision name="your_migration_name" +``` + +...and then apply it: + +```bash +make migrate +``` + +After you're done developing, just do: + +```bash +make down +``` + +Alternatively, you can setup your backend and frontend independently. + +### Backend (FastAPI + Poetry) 1. **Install [Poetry](https://python-poetry.org/docs/#installation)**. 2. Install dependencies: @@ -48,7 +81,7 @@ Create an [issue](https://github.com/ivanskv2000/evsy/issues) or open a [discuss make format && make lint ``` -### Frontend (Vue 3, Vite) +### Frontend (Vue 3 + Vite) 1. Install dependencies: @@ -67,11 +100,10 @@ Create an [issue](https://github.com/ivanskv2000/evsy/issues) or open a [discuss 3. Lint and format: ```bash - npm run format - npm run lint + npm run format && npm run lint ``` -## Opening a pull request +## 📦 Opening a pull request 1. Create a new branch: ```bash diff --git a/README.md b/README.md index 44fed94..e4c2031 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Evsy is an open-source application that helps product teams, analysts, and devel - ... and more! ## 🚀 Quick Start -To run Evsy via Docker compose, do: +To run Evsy via Docker compose, just do: 1. `cp .env.example .env` 2. `make up` From c11e0e72169a405f7bfef89973104f147b0b0e36 Mon Sep 17 00:00:00 2001 From: Ivan Skvortsov Date: Mon, 9 Jun 2025 19:55:59 +0300 Subject: [PATCH 3/4] fix: removed invalid make commands --- backend/Makefile | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/backend/Makefile b/backend/Makefile index 3e34c9f..0b11d21 100644 --- a/backend/Makefile +++ b/backend/Makefile @@ -24,12 +24,4 @@ test: poetry run pytest --cov=app --cov-report=term --cov-report=html tests test-fast: - poetry run pytest tests - -drop-db: - PYTHONPATH=./ poetry run python app/database/seeds/reset_db.py - -seed: - poetry run python -m app.database.seeds - -reseed: drop-db seed \ No newline at end of file + poetry run pytest tests \ No newline at end of file From c75f79304d3b7bf1e34669186c1e5158c32e3373 Mon Sep 17 00:00:00 2001 From: Ivan Skvortsov Date: Mon, 9 Jun 2025 19:58:52 +0300 Subject: [PATCH 4/4] fix: updated .gitignore --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 97c48a4..e39d45c 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,6 @@ __pycache__/ *.pyd node_modules/ dist/ + +# Auxiliary scripts +reset_demo.sh \ No newline at end of file