From 58f2008f344f0fb561e2596fabf3e461ecc9a0e7 Mon Sep 17 00:00:00 2001 From: tebrihk Date: Thu, 23 Apr 2026 07:44:48 +0100 Subject: [PATCH] README Update --- README.md | 361 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 207 insertions(+), 154 deletions(-) diff --git a/README.md b/README.md index f05395db..70f11ab0 100644 --- a/README.md +++ b/README.md @@ -92,18 +92,42 @@ For the full contribution and review policy, see [CONTRIBUTING.md](CONTRIBUTING. ``` src/ ├── modules/ -│ ├── auth/ # JWT, Google OAuth, Refresh tokens -│ ├── users/ # Profile, roles, preferences -│ ├── knowledge/ # Courses, content, categories -│ ├── consulting/ # 1:1 sessions, scheduling, payments -│ ├── messaging/ # Real-time chat, discussions -│ ├── notifications/ # In-app/email alerts -│ ├── analytics/ # Insights, course tracking -│ ├── web3/ # Wallet connection, token gating -│ └── file-upload/ # Cloudinary upload, avatar, files -├── config/ # TypeORM, validation, ENV configs -├── common/ # DTOs, guards, interceptors, pipes -└── main.ts # Entry point +│ ├── auth/ # JWT, session management, wallet login +│ ├── users/ # Profile management, roles, preferences +│ ├── courses/ # Course creation, enrollment, content +│ ├── payments/ # Stripe integration, transactions +│ ├── search/ # Elasticsearch integration, search APIs +│ ├── notifications/ # Real-time alerts, email, push notifications +│ ├── messaging/ # Real-time chat, discussions +│ ├── media/ # File upload, processing, CDN +│ ├── collaboration/ # Real-time collaboration features +│ ├── assessment/ # Quizzes, tests, grading +│ ├── learning-paths/ # Personalized learning journeys +│ ├── gamification/ # Points, badges, leaderboards +│ ├── moderation/ # Content moderation, reporting +│ ├── email-marketing/ # Campaign management, templates +│ ├── ab-testing/ # Feature experimentation +│ ├── data-warehouse/ # Analytics, reporting +│ ├── backup/ # Data backup and recovery +│ ├── sync/ # Data synchronization +│ ├── tenancy/ # Multi-tenant support +│ ├── security/ # Security utilities, monitoring +│ ├── caching/ # Redis caching strategies +│ ├── rate-limiting/ # API rate limiting +│ ├── observability/ # Metrics, logging, tracing +│ ├── queue/ # Background job processing +│ └── health/ # Health checks, monitoring +├── common/ +│ ├── database/ # Database configuration, connection +│ ├── decorators/ # Custom decorators +│ ├── guards/ # Authentication & authorization guards +│ ├── interceptors/ # Request/response interceptors +│ ├── pipes/ # Data validation pipes +│ ├── dto/ # Data transfer objects +│ └── utils/ # Utility functions +├── config/ # Environment configuration +├── graphql/ # GraphQL schemas and resolvers +└── main.ts # Application entry point ``` ## 🔧 Project Overview @@ -121,22 +145,77 @@ TeachLink Backend provides secure and scalable APIs to power features such as: ## 📊 Architecture -## ⚙️ Tech Stack - -| Layer | Technology | -| ------------- | -------------------------- | -| Framework | NestJS | -| Database | PostgreSQL + TypeORM | -| Blockchain | Starknet + Starknet.js | -| Realtime | WebSockets (Gateway) | -| Queues/Async | BullMQ + Redis (optional) | -| File Uploads | Cloudinary | -| Config Mgmt | @nestjs/config | -| Testing | Jest + Supertest | -| Auth | JWT + Wallet Sign-In | -| Deployment | Docker, Railway, or Fly.io | -| File Upload | Cloudinary | -| Documentation | Swagger | +### System Overview + +TeachLink Backend follows a **modular microservices architecture** built on NestJS, designed for scalability and maintainability. The system uses a layered approach with clear separation of concerns: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ API Gateway Layer │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ +│ │ REST API │ │ GraphQL │ │ WebSocket Gateway │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────┐ +│ Business Logic Layer │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ +│ │ Auth │ │ Users │ │ Courses │ │ +│ │ Module │ │ Module │ │ Module │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ +│ │ Payments │ │ Search │ │ Notifications │ │ +│ │ Module │ │ Module │ │ Module │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────┐ +│ Infrastructure Layer │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ +│ │ PostgreSQL │ │ Redis │ │ File Storage │ │ +│ │ (Primary) │ │ (Caching) │ │ (AWS S3) │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Key Architectural Patterns + +- **Modular Design**: Each business domain is encapsulated in its own module +- **Dependency Injection**: Leverages NestJS DI for loose coupling +- **Repository Pattern**: Data access abstraction via TypeORM +- **Event-Driven Architecture**: Uses EventEmitter for inter-module communication +- **CQRS Pattern**: Separation of read/write operations in complex modules +- **Feature Flags**: Dynamic module loading based on configuration + +### Data Flow + +1. **Request Processing**: API Gateway → Authentication → Authorization → Business Logic +2. **Data Persistence**: Business Logic → Repository → PostgreSQL +3. **Caching Strategy**: Redis for frequently accessed data and session management +4. **Async Operations**: BullMQ for background jobs and email processing +5. **File Handling**: AWS S3/Cloudinary for media storage with CDN distribution + +## 📦 Tech Stack + +| Layer | Technology | Purpose | +| ----------------- | ------------------------------ | ------------------------------------ | +| **Framework** | NestJS | Node.js application framework | +| **Language** | TypeScript | Type-safe JavaScript | +| **Database** | PostgreSQL + TypeORM | Primary data storage | +| **Caching** | Redis + IORedis | Session store, caching, queues | +| **Authentication**| JWT + Passport | Token-based authentication | +| **GraphQL** | Apollo Server | GraphQL API (optional) | +| **Real-time** | Socket.io | WebSocket connections | +| **File Storage** | AWS S3 + Cloudinary | Media file storage and CDN | +| **Email** | SendGrid + Nodemailer | Email delivery and marketing | +| **Payments** | Stripe | Payment processing | +| **Search** | Elasticsearch | Full-text search capabilities | +| **Queue** | BullMQ | Background job processing | +| **Monitoring** | OpenTelemetry + Prometheus | Metrics and observability | +| **Testing** | Jest + Supertest | Unit and integration tests | +| **Documentation** | Swagger | API documentation | +| **Validation** | class-validator + class-transformer | DTO validation | +| **Security** | Helmet + bcrypt | Security headers and password hashing | ## �️ Database @@ -178,7 +257,7 @@ The application uses strategic database indexes to optimize query performance, e ### Connection Pooling (TypeORM + PostgreSQL) -The backend now supports explicit database pool tuning through environment variables: +The backend supports explicit database pool tuning through environment variables: - `DATABASE_POOL_MAX` (default: `30`) - `DATABASE_POOL_MIN` (default: `5`) @@ -199,170 +278,144 @@ Sizing rule: - Formula: `DATABASE_POOL_MAX x app_instances x cluster_workers <= postgres_max_connections - reserved_connections`. - Reserve at least 20 to 30 connections for migrations, admin access, and background jobs. -Load testing checklist: +## �🚀 Getting Started -```bash -# 1) Start API -npm run start:dev +### Prerequisites -# 2) In another terminal, run concurrent load against a DB-backed endpoint -npx autocannon -c 100 -d 60 http://localhost:3000/health +- **Node.js** 18+ with npm +- **PostgreSQL** 14+ (or Docker) +- **Redis** 6+ (for caching and queues) +- **Git** for version control -# 3) Observe active connections in PostgreSQL (replace DB name) -psql -d teachlink -c "select count(*) as active_connections from pg_stat_activity where datname='teachlink';" -``` +### Quick Start + +1. **Clone the repository** -Expected result: no connection-acquire timeouts, stable latency under sustained concurrency, and active connections staying within configured pool bounds. +```bash +git clone https://github.com/teachlink/backend.git +cd teachlink_backend +``` -## �🚀 Deployment +2. **Install dependencies** -### Prerequisites +```bash +npm install +``` -- Node.js 18+ -- PostgreSQL -- Redis -- Docker (optional) +3. **Set up environment variables** -### Steps +```bash +cp .env.example .env +# Edit .env with your configuration +``` -1. Set up `.env` -2. Run `npm i` -3. Start: `npm run start:dev` or Docker Compose -4. Swagger: `http://localhost:3000/api` +4. **Start PostgreSQL and Redis** -## 🤝 Contribution +```bash +# Using Docker (recommended) +docker-compose up -d postgres redis -# 🤝 Contributing to TeachLink +# Or install locally and start services +# PostgreSQL: sudo systemctl start postgresql +# Redis: sudo systemctl start redis +``` -## 🛠 Development Workflow +5. **Run database migrations** -1. Fork the repo and clone locally. -2. Set up your environment using `.env.example` -3. Use conventional commits. -4. Run tests locally before PR. -5. Open a PR with title like: `✨ Add: Tutor Booking API` +```bash +npm run typeorm migration:run +``` -## 🧪 PR Must Include: +6. **Start the development server** -- [ ] Linked issue (`Closes #issue_number`) -- [ ] Clear title and description -- [ ] Screenshots (if UI) -- [ ] Tests (if backend) +```bash +npm run start:dev +``` -## 📬 Join the Community +7. **Access the API** -- [Telegram](t.me/teachlinkOD) +- **REST API**: http://localhost:3000 +- **API Documentation**: http://localhost:3000/api +- **Health Check**: http://localhost:3000/health -## 📁 Folder Structure +### Environment Configuration -/src -/auth → Wallet-based login, JWT, refresh tokens -/posts → CRUD for markdown posts -/topics → Topic entities and filtering -/users → Profiles, roles, reputation -/tipping → On-chain tipping integrations -/notifications → Real-time alerts (email, WebSocket) -/analytics → Activity tracking & metrics -/dao → Governance logic for post moderation -/common → DTOs, decorators, interceptors, guards +Key environment variables to configure: -yaml -Copy -Edit +```env +# Database +DATABASE_HOST=localhost +DATABASE_PORT=5432 +DATABASE_USER=postgres +DATABASE_PASSWORD=yourpassword +DATABASE_NAME=teachlink ---- +# Authentication +JWT_SECRET=your-super-secret-jwt-key +ENCRYPTION_SECRET=your-32-char-encryption-key -## 🛠 Setup Instructions +# Redis +REDIS_HOST=localhost +REDIS_PORT=6379 -1. **Clone the repository** +# External Services (Optional) +STRIPE_SECRET_KEY=your_stripe_key +AWS_ACCESS_KEY_ID=your_aws_key +AWS_SECRET_ACCESS_KEY=your_aws_secret +``` -```bash -git clone https://github.com/teachlink/backend.git -cd backend -Install dependencies +### Docker Setup -bash -Copy -Edit -npm install -Create .env file - -env -Copy -Edit -DB_HOST=localhost -DB_PORT=5432 -DB_USERNAME=postgres -DB_PASSWORD=yourpassword -DB_NAME=teachlink - -JWT_SECRET=your_jwt_secret -ENCRYPTION_SECRET=your_32_char_encryption_secret -JWT_EXPIRATION=3600 - -CLOUDINARY_API_KEY=your_key -CLOUDINARY_API_SECRET=your_secret -CLOUDINARY_CLOUD_NAME=your_name -Run PostgreSQL locally or connect to remote DB - -Start the development server - -bash -Copy -Edit -npm run start:dev -Database Migration (if applicable) +For complete development environment with Docker: -bash -Copy -Edit -npm run typeorm migration:run -📌 Key Development Milestones -✅ PostgreSQL + TypeORM setup +```bash +# Start all services +docker-compose up -d -✅ JWT-based auth with Starknet wallet login +# View logs +docker-compose logs -f -✅ Post CRUD with markdown support +# Stop services +docker-compose down +``` -✅ Topic categorization + filtering +## 🤝 Contributing -✅ Tipping logic integration +We welcome contributions from the community! Please follow our guidelines to ensure a smooth contribution process. -✅ Real-time notifications setup +### Development Workflow -🚧 Governance API for moderation +1. **Fork the repository** and clone locally +2. **Set up your environment** using `.env.example` +3. **Create a feature branch** from `develop` +4. **Make your changes** following our coding standards +5. **Run tests locally** to ensure everything works +6. **Submit a pull request** with a clear description -🚧 Contribution analytics and scoring +### Code Standards -🔐 API Modules -Module Description -Auth Module Wallet login, JWT, refresh tokens -Post Module Markdown post management -User Module Profile management and reputation -Topic Module Knowledge categories & filtering -Tip Module Send/receive tips on-chain -Notif Module In-app + external notifications -DAO Module Voting and governance decisions -File Module Upload and serve media via Cloudinary +- Use **conventional commits** (feat:, fix:, docs:, etc.) +- Follow **TypeScript** best practices +- Write **unit tests** for new features +- Update **documentation** as needed +- Ensure **linting** and **formatting** pass -✅ Contribution Guidelines -Fork the repo and create a feature branch +### Pull Request Requirements -All PRs must link to a GitHub Issue (Close #5) +- [ ] Linked issue (`Closes #issue_number`) +- [ ] Clear title and description +- [ ] Tests pass locally (`npm run test:ci`) +- [ ] Code follows style guidelines (`npm run lint:ci`) +- [ ] Documentation updated if applicable -Follow NestJS best practices and clean code principles +### Getting Help -Include unit tests for services/controllers +- 📖 [Documentation](./docs/) +- 💬 [Telegram Community](https://t.me/teachlinkOD) +- 🐛 [Report Issues](https://github.com/teachlink/backend/issues) -Join our Telegram Group for support +--- -🧪 Testing -Run unit and integration tests: +## 📄 License -bash -Copy -Edit -npm run test -📜 License MIT © 2025 TeachLink DAO -```