Coloniz Backend is a comprehensive NestJS-based backend infrastructure for the Coloniz platform, designed to index Starknet smart contracts and provide a robust GraphQL API for blockchain data access. Built with modern technologies and best practices, it serves as the foundation for decentralized community management and social features.
- Blockchain Indexing: Real-time indexing of Starknet smart contracts using Apibara
- GraphQL API: Comprehensive GraphQL API with subscriptions for real-time updates
- Community Management: Full-featured community and channel management system
- User Profiles: Complete user profile system with reputation and achievements
- Content Management: Publication system with NFT integration
- Real-time Communication: WebSocket-based messaging and notifications
- File Management: Secure file upload and processing (images, audio, video)
- Authentication: Firebase-based authentication with JWT tokens
- Moderation: Built-in content moderation and user management tools
- Analytics: Comprehensive analytics and reporting system
- Email System: Automated email notifications and templates
- Push Notifications: Web push notification support
- Framework: NestJS with TypeScript
- Database: PostgreSQL with TypeORM
- GraphQL: Apollo Server with subscriptions
- Blockchain: Starknet integration with Apibara indexing
- Messaging: Firebase Admin SDK
- File Storage: AWS S3 integration
- Queue System: Bull with Redis
- Real-time: Socket.IO for WebSocket connections
- Email: Nodemailer with Postmark support
- Monitoring: Sentry integration
- Node.js: >= 18.0.0
- Yarn: Latest version
- Docker: For containerized development
- Docker Compose: For multi-service setup
- PostgreSQL: 14+ (or use Docker)
- Redis: For queue management (or use Docker)
-
Clone the repository:
git clone https://github.com/horuslabs/coloniz-backend.git cd coloniz-backend -
Set up environment variables:
cp .env.example .env # Edit .env with your configuration -
Start the development environment:
docker compose -f docker-compose.dev.yml up --build
-
Access the application:
- GraphQL Playground: http://localhost:3000/graphql
- API Documentation: http://localhost:3000/api
-
Install dependencies:
yarn install
-
Set up the database:
# Start PostgreSQL (using Docker) docker run --name coloniz-postgres -e POSTGRES_PASSWORD=password -e POSTGRES_DB=coloniz_backend -p 5432:5432 -d postgres:14 # Or use the provided script yarn start:dev:db
-
Run database migrations:
yarn migration:run:dev
-
Start the development server:
yarn start:dev:local
Copy .env.example to .env and configure the following key variables:
# Database
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=your_password
DATABASE_NAME=coloniz_backend
# Firebase (for authentication)
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
FIREBASE_CLIENT_EMAIL=your_client_email
# AWS S3 (for file storage)
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_S3_BUCKET=your_bucket_name
# Starknet
STARKNET_RPC_URL=https://starknet-mainnet.infura.io/v3/your_project_id
APIBARA_ENDPOINT=your_apibara_endpoint
APIBARA_TOKEN=your_apibara_tokenSee .env.example for a complete list of configuration options.
The GraphQL API provides comprehensive access to all platform features:
- Queries: Fetch communities, users, publications, and more
- Mutations: Create, update, and delete resources
- Subscriptions: Real-time updates for messages, notifications, and events
Access the GraphQL Playground at http://localhost:3000/graphql
- Health Check:
GET /health - File Upload:
POST /upload - Webhooks: Various webhook endpoints for external integrations
# Run unit tests
yarn test
# Run e2e tests
yarn test:e2e
# Run tests with coverage
yarn test:cov
# Run tests in watch mode
yarn test:watch# Generate a new migration
yarn migration:generate:dev
# Run migrations
yarn migration:run:dev
# Revert last migration
yarn migration:revert:devThe application uses TypeORM with PostgreSQL. Key entities include:
- Users & Profiles: User management and profile data
- Communities: Community and subcolony management
- Channels: Communication channels within communities
- Publications: Content publishing system
- Notifications: User notification system
- Moderation: Content and user moderation tools
# Build the application
yarn build
# Start production server
yarn start:prod# Build production image
docker build -t coloniz-backend .
# Run with docker-compose
docker compose up -dWe welcome contributions! Please see our Contributing Guidelines for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes
- Run tests:
yarn test - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- Follow the existing code style and conventions
- Use TypeScript strict mode
- Write tests for new functionality
- Update documentation as needed
This project is licensed under the MIT License - see the LICENSE file for details.
Please see our Security Policy for information about reporting security vulnerabilities.
- Documentation: Check the
/docsfolder for detailed documentation - Issues: Open an issue on GitHub for bug reports or feature requests
- Discussions: Use GitHub Discussions for questions and community support
- NestJS - Progressive Node.js framework
- Starknet - Scalable blockchain platform
- Apibara - Real-time blockchain indexing
- TypeORM - TypeScript ORM
- Apollo GraphQL - GraphQL platform
This project is actively maintained and developed. Current focus areas:
- Performance optimization
- Enhanced blockchain integration
- Improved developer experience
- Extended API coverage
Built with ❤️ by the Horus Labs team