docs: easier deployment

* docs: improved README and .env.example

* docs: improved CONTRIBUTING.md

* fix: removed invalid make commands

* fix: updated .gitignore

Author: ivanskv2000

.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 
+#   <YOUR_BACKEND_URL>/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 
+#   <YOUR_BACKEND_URL>/api/v1/auth/oauth/callback
 GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
+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)

.gitignore

@@ -17,3 +17,6 @@ __pycache__/
 *.pyd
 node_modules/
 dist/
+
+# Auxiliary scripts
+reset_demo.sh

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

README.md

@@ -1,50 +1,50 @@
 # 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
-To run Evsy via Docker compose, do:
+To run Evsy via Docker compose, just 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

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
+	poetry run pytest tests