Michilis/Spanglish
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Update README with accurate setup and deploy info

Browse Source
This commit is contained in:
root
2026-01-29 21:22:04 +00:00
parent 0190a0497c
commit f550a67789
1 changed files with 98 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

256
README.md
View File

@@ -1,208 +1,148 @@
# Spanglish - Language Exchange Event Platform # Spanglish — Language Exchange Event Platform
A full-stack web application for organizing and managing language exchange events in Asunción, Paraguay. A full-stack web app for organizing and managing language exchange events (Asunción, Paraguay).
## Features ## Features
### Public Website - **Public site**: events, booking, contact, community, legal pages, bilingual (EN/ES)
- **Homepage** - Hero section with next event, about section, newsletter signup - **User dashboard**: profile, tickets, payments, sessions/security
- **Events** - Browse upcoming and past events, view event details - **Admin** (`/admin`): events, tickets/check-in, users/roles, payments, email templates, media uploads
- **Booking** - Book tickets for events with payment options - **API**: Swagger UI at `/api-docs`, OpenAPI JSON at `/openapi.json`, health check at `/health`
- **Community** - WhatsApp and social media links, community guidelines
- **Contact** - Contact form for inquiries
- **Multi-language** - English and Spanish support with easy extensibility
### Admin Dashboard (`/admin`) ## Tech stack
- **Dashboard** - Overview stats, alerts, quick actions
- **Events** - Create, edit, publish, and manage events
- **Tickets** - View bookings, check-in attendees, manage ticket status
- **Users** - Manage user accounts and roles
- **Payments** - View and confirm payments, process refunds
- **Messages** - View and respond to contact form submissions
### API - **Backend**: Node.js + TypeScript, Hono, Drizzle ORM, SQLite (default) or PostgreSQL
- **API Docs** - Swagger UI at `/api-docs` - **Auth**: JWT (via `jose`), **Argon2id** password hashing (with legacy bcrypt verification for older hashes)
- **OpenAPI Spec** - JSON specification at `/openapi.json` - **Email**: `nodemailer` (SMTP) with optional provider config
- Full REST API with JWT authentication - **Frontend**: Next.js 14 (App Router), Tailwind CSS, SWR, Heroicons
## Tech Stack ## Local development
### Backend
- **Runtime**: Node.js with TypeScript
- **Framework**: Hono (fast, lightweight)
- **Database**: SQLite (default) or PostgreSQL
- **ORM**: Drizzle ORM
- **Authentication**: JWT with bcrypt password hashing
- **API Documentation**: OpenAPI 3.0 / Swagger UI
### Frontend
- **Framework**: Next.js 14 (App Router)
- **Styling**: Tailwind CSS
- **Icons**: Heroicons
- **State Management**: React Context
- **HTTP Client**: SWR / Fetch API
- **Notifications**: React Hot Toast
## Getting Started
### Prerequisites ### Prerequisites
- Node.js 18+ - Node.js 18+
- npm or yarn - npm
### Installation ### Setup
1. Clone the repository:
```bash
git clone <repository-url>
cd Spanglish
```
2. Install dependencies:
```bash ```bash
npm install npm install
```
3. Set up environment variables:
```bash
# Backend
cp backend/.env.example backend/.env cp backend/.env.example backend/.env
# Edit backend/.env with your settings cp frontend/.env.example frontend/.env
``` ```
4. Initialize the database: ### Initialize database (SQLite by default)
```bash ```bash
npm run db:migrate npm run db:migrate
``` ```
5. Start the development servers: ### Run
```bash ```bash
npm run dev npm run dev
``` ```
The application will be available at: Default URLs:
- Frontend: http://localhost:3002
- Backend API: http://localhost:3001
- API Docs: http://localhost:3001/api-docs
### First User = Admin - Frontend: `http://localhost:3002`
- Backend API: `http://localhost:3001`
- API docs: `http://localhost:3001/api-docs`
The first user to register becomes the admin. Register at `/register` to create the admin account. ### First user becomes admin
## Database Configuration The first user to register becomes the **admin**. Register at `/register`.
### SQLite (Default) ## Useful scripts (workspace)
No additional configuration needed. Database file is created at `backend/data/spanglish.db`.
Run these from the repo root:
```bash
npm run dev
npm run build
npm run start
npm run db:generate
npm run db:migrate
npm run db:studio
```
You can also run per workspace:
```bash
npm run dev --workspace=backend
npm run dev --workspace=frontend
```
## Environment variables
### Backend (`backend/.env`)
Key settings (see `backend/.env.example` for the full list):
- **DB**: `DB_TYPE=sqlite|postgres`, `DATABASE_URL=./data/spanglish.db` (or Postgres URL)
- **Auth**: `JWT_SECRET` (change in production)
- **URLs/ports**: `PORT`, `API_URL`, `FRONTEND_URL`
- **Email**: `EMAIL_PROVIDER` (`console|smtp|resend`) and corresponding credentials
- **Payments (optional)**: Stripe/MercadoPago/LNbits configuration
### Frontend (`frontend/.env`)
Key settings (see `frontend/.env.example`):
- **Server port**: `PORT=3002`
- **API base URL**: `NEXT_PUBLIC_API_URL` (optional)
- Leave empty to use same-origin `/api` (recommended when running behind nginx)
- In local dev, Next.js rewrites `/api/*` and `/uploads/*` to the backend
- **Social links (optional)**: `NEXT_PUBLIC_WHATSAPP`, `NEXT_PUBLIC_INSTAGRAM`, etc.
## Database
### SQLite (default)
- DB file defaults to `backend/data/spanglish.db` (via `DATABASE_URL=./data/spanglish.db`)
- Run migrations with `npm run db:migrate`
### PostgreSQL ### PostgreSQL
Update `backend/.env`:
Set in `backend/.env`:
```env ```env
DB_TYPE=postgres DB_TYPE=postgres
DATABASE_URL=postgresql://user:password@localhost:5432/spanglish DATABASE_URL=postgresql://user:password@localhost:5432/spanglish
``` ```
## Project Structure Then run:
``` ```bash
Spanglish/ npm run db:migrate
├── backend/
│ ├── src/
│ │ ├── db/ # Database schema and migrations
│ │ ├── lib/ # Utilities (auth, helpers)
│ │ ├── routes/ # API routes
│ │ └── index.ts # Server entry point
│ └── drizzle.config.ts
├── frontend/
│ ├── src/
│ │ ├── app/ # Next.js pages
│ │ │ ├── (public)/ # Public pages
│ │ │ └── admin/ # Admin dashboard
│ │ ├── components/ # React components
│ │ ├── context/ # React contexts
│ │ ├── i18n/ # Internationalization
│ │ └── lib/ # API client, utilities
│ └── tailwind.config.js
└── package.json # Monorepo workspace config
``` ```
## Adding New Languages ## Production deployment (nginx + systemd)
The i18n system is designed for easy extensibility: This repo includes example configs in `deploy/`:
1. Create a new locale file at `frontend/src/i18n/locales/{code}.json` - **systemd**: `deploy/spanglish-backend.service`, `deploy/spanglish-frontend.service`
2. Copy structure from `en.json` and translate - Backend runs on **3018**, frontend on **3019** by default (see the unit files)
3. Update `frontend/src/i18n/index.ts`: - Backend needs write access to `backend/data` and `backend/uploads`
- **nginx**:
- `deploy/spanglish_upstreams.conf` defines upstreams for ports 3018/3019
- `deploy/front-end_nginx.conf` proxies `/api` and `/uploads` to the backend and everything else to the frontend
- `deploy/back-end_nginx.conf` is a dedicated API vhost example with CORS handling
```typescript Typical production flow:
import pt from './locales/pt.json';
export type Locale = 'en' | 'es' | 'pt'; ```bash
npm ci
export const locales: Record<Locale, typeof en> = { npm run build
en, npm run db:migrate
es,
pt, // Add new locale
};
export const localeNames: Record<Locale, string> = {
en: 'English',
es: 'Español',
pt: 'Português', // Add display name
};
export const localeFlags: Record<Locale, string> = {
en: '🇺🇸',
es: '🇪🇸',
pt: '🇧🇷', // Add flag
};
``` ```
## API Endpoints Then install/enable the systemd services and nginx configs for your server.
### Authentication ## Documentation
- `POST /api/auth/register` - Register new user
- `POST /api/auth/login` - Login
- `GET /api/auth/me` - Get current user
### Events - **Specs / notes**: `about/`
- `GET /api/events` - List events - **Legal docs**: `frontend/legal/`
- `GET /api/events/:id` - Get event
- `POST /api/events` - Create event (admin)
- `PUT /api/events/:id` - Update event (admin)
- `DELETE /api/events/:id` - Delete event (admin)
### Tickets
- `POST /api/tickets` - Book ticket
- `GET /api/tickets/:id` - Get ticket
- `POST /api/tickets/:id/checkin` - Check in (staff)
### Users
- `GET /api/users` - List users (admin)
- `PUT /api/users/:id` - Update user
### Payments
- `GET /api/payments` - List payments (admin)
- `PUT /api/payments/:id` - Update payment status
- `POST /api/payments/:id/refund` - Process refund
### Contacts
- `POST /api/contacts` - Submit contact form
- `POST /api/contacts/subscribe` - Subscribe to newsletter
## User Roles
- **admin** - Full access to all features
- **organizer** - Manage events, tickets, view payments
- **staff** - Check-in attendees, view ticket info
- **marketing** - Access to subscriber lists, analytics
- **user** - Public user, can book events
## Brand Colors
- Primary Yellow: `#FFD84D`
- Primary Dark: `#111111`
- Primary White: `#FFFFFF`
- Secondary Gray: `#F5F5F5`
- Accent Blue: `#2F80ED`
## License ## License