till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-28 23:52:54 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

refactor: restructure

Browse source 
monorepo with apps/ and services/
  directories
This commit is contained in:
Wuesteon 2025-11-26 03:03:24 +01:00
parent 25824ed0ac
commit ff80aeec1f
4062 changed files with 2592 additions and 1278 deletions
Download patch file Download diff file Expand all files Collapse all files

355
mana-core-auth/QUICKSTART.md
View file

@ -1,355 +0,0 @@
# Quick Start Guide - Mana Core Auth
Get the authentication system running in 5 minutes!
## Prerequisites
- Node.js 20+
- pnpm 9.15.0+
- Docker & Docker Compose
- OpenSSL (for key generation)
## Step 1: Generate JWT Keys (2 minutes)
```bash
cd mana-core-auth
chmod +x scripts/generate-keys.sh
./scripts/generate-keys.sh
```
This will create `private.pem` and `public.pem` and show you the formatted keys for .env
## Step 2: Configure Environment (1 minute)
```bash
# Copy the example
cp .env.example .env
# Edit .env and add:
# 1. JWT keys from Step 1
# 2. Change default passwords
# 3. Add Stripe test keys (optional for now)
```
**Minimum required changes in .env:**
```env
POSTGRES_PASSWORD=your-secure-password-here
REDIS_PASSWORD=your-redis-password-here
JWT_PRIVATE_KEY="your-private-key-here"
JWT_PUBLIC_KEY="your-public-key-here"
```
## Step 3: Start Infrastructure (30 seconds)
```bash
# From monorepo root
docker-compose up postgres redis -d
# Wait for services to be healthy
docker-compose ps
```
## Step 4: Run Migrations (10 seconds)
```bash
cd mana-core-auth
pnpm migration:run
```
Expected output:
```
Running migrations...
Migrations completed successfully
```
## Step 5: Start the Service (10 seconds)
```bash
pnpm start:dev
```
You should see:
```
🚀 Mana Core Auth running on: http://localhost:3001
📚 Environment: development
```
## Test It Works!
### 1. Register a User
```bash
curl -X POST http://localhost:3001/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com",
"password": "SecurePass123!",
"name": "Test User"
}'
```
Expected response:
```json
{
"id": "uuid-here",
"email": "test@example.com",
"name": "Test User",
"createdAt": "2025-11-25T..."
}
```
### 2. Login
```bash
curl -X POST http://localhost:3001/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com",
"password": "SecurePass123!"
}'
```
Expected response:
```json
{
"user": {
"id": "uuid-here",
"email": "test@example.com",
"name": "Test User",
"role": "user"
},
"accessToken": "eyJhbGciOiJSUzI1NiIs...",
"refreshToken": "long-random-string",
"expiresIn": 900,
"tokenType": "Bearer"
}
```
### 3. Check Credit Balance
```bash
# Replace YOUR_TOKEN with accessToken from login
curl -X GET http://localhost:3001/api/v1/credits/balance \
-H "Authorization: Bearer YOUR_TOKEN"
```
Expected response:
```json
{
"balance": 0,
"freeCreditsRemaining": 150,
"totalEarned": 0,
"totalSpent": 0,
"dailyFreeCredits": 5
}
```
### 4. Use Some Credits
```bash
curl -X POST http://localhost:3001/api/v1/credits/use \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 10,
"appId": "test",
"description": "Test credit usage",
"idempotencyKey": "test-unique-123"
}'
```
Expected response:
```json
{
"success": true,
"transaction": {
"id": "uuid-here",
"userId": "uuid-here",
"type": "usage",
"status": "completed",
"amount": -10,
"balanceBefore": 150,
"balanceAfter": 140,
"appId": "test",
"description": "Test credit usage"
},
"newBalance": {
"balance": 0,
"freeCreditsRemaining": 140,
"totalSpent": 10
}
}
```
## You're Done! 🎉
The authentication system is now running and ready to use.
## Next Steps
1. **Integrate with your apps**
- Add the auth endpoints to your mobile/web apps
- Implement token refresh logic
- Store tokens securely (SecureStore on mobile, httpOnly cookies on web)
2. **Add Stripe integration**
- Get Stripe API keys
- Add webhook endpoint
- Create credit packages
- Test payment flow
3. **Production deployment**
- Follow DOCKER_DEPLOYMENT_GUIDE.md
- Set up on VPS
- Configure domain and SSL
- Enable monitoring
## Troubleshooting
### "Connection refused" to PostgreSQL
**Problem:** Database not ready yet
**Solution:**
```bash
docker-compose ps # Check if postgres is healthy
docker-compose logs postgres # Check logs
```
### "JWT key not found" error
**Problem:** JWT keys not set in .env
**Solution:**
```bash
# Run the key generator again
./scripts/generate-keys.sh
# Copy the keys to .env
# Make sure they're properly escaped (with \n for newlines)
```
### Migrations fail
**Problem:** Database schema issues
**Solution:**
```bash
# Drop and recreate database
docker-compose down -v
docker-compose up postgres -d
# Wait 10 seconds
pnpm migration:run
```
### Port 3001 already in use
**Problem:** Another service is using the port
**Solution:**
```bash
# Change PORT in .env
echo "PORT=3002" >> .env
# Or kill the process using 3001
lsof -ti:3001 | xargs kill
```
## Development Tips
### Watch Database Changes
```bash
pnpm db:studio
# Opens Drizzle Studio at http://localhost:4983
```
### View Logs
```bash
# Application logs
# The service prints to console when running in dev mode
# Docker logs
docker-compose logs -f postgres
docker-compose logs -f redis
```
### Run Tests
```bash
pnpm test
pnpm test:watch
pnpm test:cov
```
### Format Code
```bash
pnpm format
pnpm lint
```
## Common Commands
```bash
# Start dev server
pnpm start:dev
# Build for production
pnpm build
# Start production server
pnpm start:prod
# Generate new migration
pnpm migration:generate
# Run migrations
pnpm migration:run
# Open database GUI
pnpm db:studio
```
## Environment Variables Reference
### Required
- `DATABASE_URL` - PostgreSQL connection string
- `JWT_PRIVATE_KEY` - RS256 private key (PEM format)
- `JWT_PUBLIC_KEY` - RS256 public key (PEM format)
### Optional (have defaults)
- `PORT` - Server port (default: 3001)
- `NODE_ENV` - Environment (default: development)
- `REDIS_HOST` - Redis host (default: localhost)
- `CORS_ORIGINS` - Allowed origins (default: localhost:3000,localhost:8081)
- `CREDITS_SIGNUP_BONUS` - Signup credits (default: 150)
- `CREDITS_DAILY_FREE` - Daily free credits (default: 5)
### For Production
- `STRIPE_SECRET_KEY` - Stripe secret key
- `STRIPE_WEBHOOK_SECRET` - Stripe webhook signing secret
- `ACME_EMAIL` - Email for Let's Encrypt SSL
- `AUTH_DOMAIN` - Domain name for the service
## Resources
- **Full Documentation:** `README.md`
- **Implementation Summary:** `IMPLEMENTATION_SUMMARY.md`
- **Master Plan:** `../../.hive-mind/MASTER_PLAN_CENTRAL_AUTH_SYSTEM.md`
- **Docker Guide:** `../../.hive-mind/DOCKER_DEPLOYMENT_GUIDE.md`
## Support
If you encounter issues:
1. Check this guide first
2. Review the logs
3. Consult the master plan
4. Ask the development team
---
**Time to Complete:** ~5 minutes
**Status:** Ready for Development & Testing