Flow Docs

guide

17 min read

Flow - Development Guide

Version: 1.0.0 Last Updated: March 10, 2026

Documento pre-migrazione Supabase-only

Questa guida è stata scritta quando Flow usava microservizi Node.js + MongoDB + Redis. Dopo la migrazione Supabase-only del 2026-03-29 molte sezioni non sono più accurate — in particolare i prerequisiti (MongoDB, Redis, Docker Compose non servono più), la struttura del progetto e il workflow di setup.

Setup attuale (semplificato):

  1. npm install in flow_backend/web/
  2. .env con NEXT_PUBLIC_SUPABASE_URL + NEXT_PUBLIC_SUPABASE_ANON_KEY
  3. npm run dev

Per il mobile: flutter pub get && flutter run in flow_mobile/.

Vedi Architettura Overview per lo stack reale. Questa guida sarà riscritta o archiviata nei prossimi sprint.

Table of Contents

  1. Getting Started
  2. Development Environment Setup
  3. Project Structure
  4. Development Workflow
  5. Coding Standards
  6. Testing Strategy
  7. Debugging
  8. Common Tasks
  9. Troubleshooting
  10. Best Practices

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js >= 18.0.0
  • npm >= 8.0.0
  • Python >= 3.9
  • Flutter >= 3.6.0
  • Docker >= 20.0
  • Docker Compose >= 2.0
  • Git >= 2.30
  • PostgreSQL >= 14 (if running locally)
  • MongoDB >= 6.0 (if running locally)
  • Redis >= 7.0 (if running locally)
  • VS Code with extensions:
    • Flutter
    • Dart
    • ESLint
    • Prettier
    • Docker
    • MongoDB for VS Code
    • PostgreSQL
  • Postman or Insomnia for API testing
  • MongoDB Compass for database inspection
  • pgAdmin or DBeaver for PostgreSQL

Development Environment Setup

1. Clone the Repository

git clone https://github.com/EliaCoon/Flow.git
cd Flow

2. Environment Configuration

Root Project

cp .env.example .env

Edit .env with your configuration:

# MongoDB
MONGODB_URI=mongodb://admin:password123@localhost:27017/flow?authSource=admin
 
# Redis
REDIS_URL=redis://:redis123@localhost:6379
 
# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d
 
# Services
USER_SERVICE_URL=http://localhost:3001
EVENT_SERVICE_URL=http://localhost:3002
SOCIAL_SERVICE_URL=http://localhost:3003
NOTIFICATION_SERVICE_URL=http://localhost:3004
REALTIME_SERVICE_URL=http://localhost:3005
 
# Elasticsearch (optional)
ELASTICSEARCH_URL=http://localhost:9200
 
# Firebase (for push notifications)
FIREBASE_PROJECT_ID=your-firebase-project-id
# ... other Firebase config
 
# SendGrid (for emails)
SENDGRID_API_KEY=your-sendgrid-api-key
SENDGRID_FROM_EMAIL=noreply@flowapp.com

Admin Portal

cd admin-portal
cp .env.example .env.local

Edit admin-portal/.env.local:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
 
# API Gateway (for proxying requests)
NEXT_PUBLIC_API_URL=http://localhost:3000

Mobile App

Edit mobile/flow_app/lib/core/constants/app_constants.dart:

class AppConstants {
  static const String supabaseUrl = 'https://your-project.supabase.co';
  static const String supabaseAnonKey = 'your-anon-key';
  static const String apiGatewayUrl = 'http://localhost:3000';
  static const String socketUrl = 'http://localhost:3005';
}

3. Install Dependencies

Backend Services

# Install root dependencies
npm install
 
# Install all backend services
cd backend
npm run install:all
 
# Or install individually
cd backend/api-gateway && npm install
cd backend/user-service && npm install
cd backend/event-service && npm install
cd backend/social-service && npm install
cd backend/notification-service && npm install
cd backend/realtime-service && npm install

Admin Portal

cd admin-portal
npm install

Mobile App

cd mobile/flow_app
flutter pub get

AI Services

cd ai-services
pip install -r requirements.txt

4. Database Setup

# Start only databases
docker-compose up -d mongodb redis elasticsearch
 
# Or start all services
docker-compose up -d

Option B: Local Installation

Install MongoDB, Redis, and Elasticsearch locally and ensure they’re running.

Initialize Supabase

  1. Create a project at supabase.com
  2. Run migrations:
cd supabase
 
# Using Supabase CLI (recommended)
supabase db push
 
# Or manually run migrations in Supabase SQL Editor
# Copy contents of each migration file in supabase/migrations/ and execute in order
  1. Seed data (optional):
# Run database_seed.sql in Supabase SQL Editor

5. Start Development Servers

All Services at Once

# From project root
npm run dev

This will start:

  • API Gateway (port 3000)
  • All backend microservices (ports 3001-3005)
  • AI services (ports 8001-8002)

Individual Services

# API Gateway
cd backend/api-gateway && npm run dev
 
# User Service
cd backend/user-service && npm run dev
 
# Event Service
cd backend/event-service && npm run dev
 
# Social Service
cd backend/social-service && npm run dev
 
# Notification Service
cd backend/notification-service && npm run dev
 
# Realtime Service
cd backend/realtime-service && npm run dev
 
# Admin Portal
cd admin-portal && npm run dev
 
# Mobile App
cd mobile/flow_app && flutter run
 
# AI Services
cd ai-services/recommendation-engine && python -m uvicorn main:app --reload --port 8001
cd ai-services/matchmaking-service && python -m uvicorn main:app --reload --port 8002

6. Verify Installation

Visit these URLs to verify services are running:

Project Structure

Flow/
├── .agent/                       # AI agent rules and workflows
├── .git/                         # Git repository
├── .github/                      # GitHub Actions CI/CD
├── .trae/                        # Legacy AI assistant documents
├── .vercel/                      # Vercel deployment config
│
├── admin-portal/                 # Next.js Admin & Vendor Dashboard
│   ├── app/                      # App Router pages
│   │   ├── admin/                # Admin dashboard routes
│   │   │   ├── (dashboard)/      # Protected dashboard layout
│   │   │   │   ├── analytics/
│   │   │   │   ├── audit/
│   │   │   │   ├── campaigns/
│   │   │   │   ├── chats/
│   │   │   │   ├── dashboard/
│   │   │   │   ├── events/
│   │   │   │   ├── posts/
│   │   │   │   ├── reports/
│   │   │   │   ├── settings/
│   │   │   │   └── users/
│   │   │   └── login/
│   │   ├── vendor/               # Vendor portal routes
│   │   │   └── (dashboard)/
│   │   │       ├── campaigns/
│   │   │       ├── dashboard/
│   │   │       ├── events/
│   │   │       ├── orders/
│   │   │       ├── products/
│   │   │       ├── profile/
│   │   │       ├── settings/
│   │   │       └── venues/
│   │   ├── auth/                 # Public auth pages
│   │   ├── layout.tsx            # Root layout
│   │   └── page.tsx              # Landing page
│   ├── components/               # Reusable React components
│   │   ├── ui/                   # Base UI components
│   │   └── ...                   # Feature components
│   ├── contexts/                 # React contexts
│   ├── hooks/                    # Custom React hooks
│   ├── lib/                      # Utilities
│   │   ├── api/                  # API client functions
│   │   ├── schemas/              # Zod validation schemas
│   │   └── utils/                # Helper functions
│   ├── providers/                # Context providers
│   ├── public/                   # Static assets
│   ├── tests/                    # Test files
│   ├── types/                    # TypeScript type definitions
│   ├── .env.local                # Environment variables (gitignored)
│   ├── next.config.ts            # Next.js configuration
│   ├── package.json
│   ├── tailwind.config.ts        # Tailwind CSS config
│   └── tsconfig.json             # TypeScript config
│
├── mobile/flow_app/              # Flutter Mobile App
│   ├── lib/
│   │   ├── core/                 # Core functionality
│   │   │   ├── auth/             # Authentication service
│   │   │   ├── constants/        # App constants
│   │   │   ├── models/           # Data models
│   │   │   ├── network/          # API services
│   │   │   ├── router/           # GoRouter configuration
│   │   │   ├── services/         # Core services
│   │   │   ├── storage/          # Local storage
│   │   │   ├── theme/            # App theme
│   │   │   └── utils/            # Utility functions
│   │   ├── features/             # Feature modules
│   │   │   ├── auth/             # Authentication screens
│   │   │   ├── campaigns/        # Campaign management
│   │   │   ├── dashboard/        # User dashboard
│   │   │   ├── events/           # Event discovery & management
│   │   │   ├── feed/             # Social feed
│   │   │   ├── gamification/     # Points, badges
│   │   │   ├── home/             # Home screen
│   │   │   ├── messaging/        # Chat & messaging
│   │   │   ├── notifications/    # Notifications
│   │   │   ├── onboarding/       # User onboarding
│   │   │   ├── pr/               # PR features
│   │   │   ├── profile/          # User profile
│   │   │   ├── reviews/          # Event reviews
│   │   │   ├── search/           # Search functionality
│   │   │   ├── settings/         # App settings
│   │   │   ├── social/           # Social features
│   │   │   └── tickets/          # Ticketing
│   │   ├── shared/               # Shared widgets & utilities
│   │   │   ├── notifiers/        # Riverpod notifiers
│   │   │   ├── services/         # Shared services
│   │   │   └── widgets/          # Reusable widgets
│   │   ├── l10n/                 # Localization files
│   │   └── main.dart             # App entry point
│   ├── android/                  # Android-specific code
│   ├── ios/                      # iOS-specific code
│   ├── assets/                   # Images, fonts, animations
│   ├── pubspec.yaml              # Flutter dependencies
│   └── analysis_options.yaml     # Dart linter config
│
├── backend/                      # Node.js Microservices
│   ├── api-gateway/              # API Gateway (Port 3000)
│   │   ├── src/
│   │   │   ├── middleware/       # Auth, rate limit, logging
│   │   │   ├── routes/           # Route definitions
│   │   │   └── server.js         # Express server
│   │   ├── config/               # Configuration
│   │   └── package.json
│   ├── user-service/             # User Service (Port 3001)
│   │   ├── src/
│   │   │   ├── controllers/      # Request handlers
│   │   │   ├── middleware/       # Service middleware
│   │   │   ├── models/           # Mongoose models
│   │   │   ├── routes/           # API routes
│   │   │   ├── services/         # Business logic
│   │   │   ├── utils/            # Utilities
│   │   │   └── app.js            # Express app
│   │   └── package.json
│   ├── event-service/            # Event Service (Port 3002)
│   │   └── [similar structure]
│   ├── social-service/           # Social Service (Port 3003)
│   │   └── [similar structure]
│   ├── notification-service/     # Notification Service (Port 3004)
│   │   ├── src/
│   │   │   ├── services/         # Channel adapters (FCM, email, SMS)
│   │   │   ├── workers/          # Bull queue workers
│   │   │   └── ...
│   │   └── package.json
│   ├── realtime-service/         # Realtime Service (Port 3005)
│   │   ├── src/
│   │   │   ├── events/           # Socket.IO event handlers
│   │   │   ├── middleware/       # Socket middleware
│   │   │   └── ...
│   │   └── package.json
│   └── package.json              # Workspace package.json
│
├── ai-services/                  # Python AI/ML Services
│   ├── recommendation-engine/    # Event Recommendations (Port 8001)
│   │   ├── main.py               # FastAPI app
│   │   ├── models/               # ML models
│   │   └── requirements.txt
│   ├── matchmaking-service/      # User Matchmaking (Port 8002)
│   │   └── [similar structure]
│   ├── models/                   # Trained model files
│   └── requirements.txt          # Python dependencies
│
├── supabase/                     # Supabase Configuration
│   ├── migrations/               # SQL migration files (chronological)
│   │   ├── 20240101000000_initial_schema.sql
│   │   ├── 20240220_deep_schema_expansion.sql
│   │   ├── 20240224_tags_ecosystem.sql
│   │   ├── 20240226_integrity_and_rules.sql
│   │   ├── 20240227_*.sql
│   │   ├── 20240301_*.sql
│   │   └── 20240305_mvp_foundations.sql
│   └── migrations_backup/        # Old/deprecated migrations
│
├── docs/                         # Documentation
│   ├── PROJECT_OVERVIEW.md       # High-level project overview
│   ├── TECHNICAL_ARCHITECTURE.md # Technical architecture details
│   ├── DATABASE_SCHEMA.md        # Database schemas
│   ├── API_DOCUMENTATION.md      # API reference
│   ├── DEVELOPMENT_GUIDE.md      # This file
│   ├── DEPLOYMENT_GUIDE.md       # Deployment instructions
│   ├── ROADMAP.md                # Product roadmap
│   ├── architecture-improvements.md  # Architecture review
│   ├── codebase-technical-documentation.md  # Legacy docs
│   └── issues/                   # Architecture issue tracking
│
├── infrastructure/               # Docker & K8s configs
│   ├── docker/
│   └── kubernetes/
│
├── scripts/                      # Utility scripts
│   ├── mongo-init.js             # MongoDB initialization
│   └── ...
│
├── .env                          # Environment variables (gitignored)
├── .env.example                  # Environment template
├── .gitignore
├── docker-compose.yml            # Docker Compose for local dev
├── package.json                  # Root package.json
├── README.md                     # Quick start guide
└── database_seed.sql             # Supabase seed data

Development Workflow

1. Branch Strategy

We use Git Flow with the following branches:

  • main: Production-ready code
  • develop: Integration branch for features
  • feature/*: New features
  • bugfix/*: Bug fixes
  • hotfix/*: Production hotfixes
  • release/*: Release candidates

Creating a Feature Branch

# Update develop
git checkout develop
git pull origin develop
 
# Create feature branch
git checkout -b feature/your-feature-name
 
# Work on your feature...
 
# Commit changes
git add .
git commit -m "feat: add your feature description"
 
# Push to remote
git push origin feature/your-feature-name
 
# Create pull request on GitHub

2. Commit Message Convention

We follow Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding or updating tests
  • build: Build system changes
  • ci: CI/CD changes
  • chore: Other changes

Examples:

git commit -m "feat(events): add location-based event search"
git commit -m "fix(auth): resolve JWT token expiration issue"
git commit -m "docs(api): update API documentation for user endpoints"
git commit -m "refactor(mobile): extract event card to reusable widget"

3. Pull Request Process

  1. Create PR on GitHub with descriptive title and description
  2. Link Issues: Reference related issues (#123)
  3. Request Review: Assign reviewers
  4. CI Checks: Ensure all CI checks pass
  5. Code Review: Address review comments
  6. Merge: Squash and merge to develop

4. Code Review Checklist

  • Code follows project coding standards
  • No hardcoded credentials or secrets
  • Tests added/updated and passing
  • Documentation updated
  • No console.log or debug statements
  • Error handling implemented
  • Performance considerations addressed
  • Security implications reviewed

Coding Standards

JavaScript/TypeScript (Backend & Admin Portal)

Style Guide

  • Formatter: Prettier
  • Linter: ESLint
  • Indentation: 2 spaces
  • Quotes: Single quotes for strings
  • Semicolons: Required

Configuration

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "printWidth": 100
}
// .eslintrc.json
{
  "extends": ["next/core-web-vitals", "prettier"],
  "rules": {
    "no-console": "warn",
    "no-unused-vars": "error"
  }
}

Best Practices

// ✅ Good
const fetchUserProfile = async (userId) => {
  try {
    const response = await api.get(`/users/${userId}`);
    return response.data;
  } catch (error) {
    logger.error('Failed to fetch user profile', { userId, error });
    throw new AppError('Unable to fetch user profile', 500);
  }
};
 
// ❌ Bad
async function getUserProfile(userId) {
  let response = await api.get('/users/' + userId);
  console.log(response);
  return response.data;
}

Dart/Flutter (Mobile)

Style Guide

  • Formatter: dart format
  • Linter: flutter analyze
  • Indentation: 2 spaces
  • Line length: 80 characters (recommended)

Configuration

# analysis_options.yaml
include: package:flutter_lints/flutter.yaml
 
linter:
  rules:
    - prefer_const_constructors
    - prefer_final_fields
    - avoid_print
    - avoid_unnecessary_containers

Best Practices

// ✅ Good
class EventCard extends ConsumerWidget {
  const EventCard({
    Key? key,
    required this.event,
    this.onTap,
  }) : super(key: key);
 
  final Event event;
  final VoidCallback? onTap;
 
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    return Card(
      child: ListTile(
        title: Text(event.title),
        subtitle: Text(event.description),
        onTap: onTap,
      ),
    );
  }
}
 
// ❌ Bad
class EventCard extends StatelessWidget {
  Event? event;
  var onTap;
 
  EventCard({this.event, this.onTap});
 
  @override
  Widget build(BuildContext context) {
    return Card(
      child: ListTile(
        title: Text(event!.title),
        subtitle: Text(event!.description),
        onTap: () {
          print('Tapped');
          onTap();
        },
      ),
    );
  }
}

Python (AI Services)

Style Guide

  • Formatter: Black
  • Linter: Flake8
  • Type Hints: Required
  • Docstrings: Google style

Best Practices

# ✅ Good
from typing import List, Optional
import logging
 
logger = logging.getLogger(__name__)
 
async def recommend_events(
    user_id: str,
    limit: int = 10,
    filters: Optional[dict] = None
) -> List[dict]:
    """
    Generate personalized event recommendations for a user.
 
    Args:
        user_id: The unique identifier of the user
        limit: Maximum number of recommendations to return
        filters: Optional filters to apply
 
    Returns:
        List of recommended events with scores
 
    Raises:
        ValueError: If user_id is invalid
        DatabaseError: If database query fails
    """
    try:
        # Implementation
        pass
    except Exception as e:
        logger.error(f"Failed to generate recommendations: {e}")
        raise

Testing Strategy

Backend Services (Jest)

# Run all tests
npm test
 
# Run tests for specific service
cd backend/user-service && npm test
 
# Run tests in watch mode
npm test -- --watch
 
# Generate coverage report
npm test -- --coverage

Example Test

// user-service/src/controllers/__tests__/auth.test.js
const request = require('supertest');
const app = require('../../app');
 
describe('POST /api/auth/register', () => {
  it('should register a new user', async () => {
    const response = await request(app)
      .post('/api/auth/register')
      .send({
        email: 'test@example.com',
        password: 'SecurePass123!',
        firstName: 'Test',
        lastName: 'User',
      })
      .expect(201);
 
    expect(response.body).toHaveProperty('token');
    expect(response.body.user).toHaveProperty('id');
  });
 
  it('should fail with invalid email', async () => {
    const response = await request(app)
      .post('/api/auth/register')
      .send({
        email: 'invalid-email',
        password: 'SecurePass123!',
      })
      .expect(400);
 
    expect(response.body).toHaveProperty('error');
  });
});

Admin Portal (Vitest)

cd admin-portal
npm test

Example Test

// admin-portal/__tests__/components/EventCard.test.tsx
import { render, screen } from '@testing-library/react';
import { EventCard } from '@/components/EventCard';
 
describe('EventCard', () => {
  const mockEvent = {
    id: '1',
    title: 'Test Event',
    description: 'Test Description',
    start_date: '2026-04-01',
  };
 
  it('renders event information', () => {
    render(<EventCard event={mockEvent} />);
    expect(screen.getByText('Test Event')).toBeInTheDocument();
    expect(screen.getByText('Test Description')).toBeInTheDocument();
  });
});

Mobile App (Flutter)

cd mobile/flow_app
flutter test

Example Test

// mobile/flow_app/test/widgets/event_card_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:flow_app/features/events/widgets/event_card.dart';
 
void main() {
  testWidgets('EventCard displays event information', (WidgetTester tester) async {
    final event = Event(
      id: '1',
      title: 'Test Event',
      description: 'Test Description',
    );
 
    await tester.pumpWidget(
      MaterialApp(
        home: Scaffold(
          body: EventCard(event: event),
        ),
      ),
    );
 
    expect(find.text('Test Event'), findsOneWidget);
    expect(find.text('Test Description'), findsOneWidget);
  });
}

Debugging

Backend Services

Using VS Code Debugger

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug API Gateway",
      "cwd": "${workspaceFolder}/backend/api-gateway",
      "program": "${workspaceFolder}/backend/api-gateway/src/server.js",
      "env": {
        "NODE_ENV": "development"
      }
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Debug User Service",
      "cwd": "${workspaceFolder}/backend/user-service",
      "program": "${workspaceFolder}/backend/user-service/src/app.js"
    }
  ]
}

Logging

All services use structured logging. Check logs:

# View logs in real-time
tail -f backend/notification-service/logs/combined.log
 
# Search logs
grep "ERROR" backend/user-service/logs/combined.log

Mobile App

Flutter DevTools

# Run app in debug mode
flutter run
 
# Open DevTools
flutter pub global activate devtools
flutter pub global run devtools

Debug Prints

import 'package:flow_app/core/services/log_service.dart';
 
// Use LogService instead of print()
LogService.instance.log('Debug message', data);
LogService.instance.log('Error occurred', error, stackTrace);

Common Tasks

Create New Database Migration (Supabase)

-- supabase/migrations/20260310_your_migration_name.sql
-- Description: What this migration does
 
-- Add your SQL here
ALTER TABLE public.events
  ADD COLUMN new_field TEXT;
 
-- Add indexes if needed
CREATE INDEX idx_events_new_field ON public.events(new_field);

Apply migration:

# Using Supabase CLI
supabase db push
 
# Or run manually in Supabase SQL Editor

Add New API Endpoint

  1. Define route in service (e.g., backend/event-service/src/routes/events.js):
router.post('/events/:id/like', authMiddleware, likeEvent);
  1. Implement controller:
// backend/event-service/src/controllers/eventController.js
exports.likeEvent = catchAsync(async (req, res) => {
  const { id } = req.params;
  const userId = req.user.id;
 
  const event = await Event.findById(id);
  if (!event) {
    throw new AppError('Event not found', 404);
  }
 
  // Add like logic
  if (!event.social.likes.includes(userId)) {
    event.social.likes.push(userId);
    event.social.likeCount += 1;
    await event.save();
  }
 
  res.status(200).json({
    success: true,
    data: { likes: event.social.likeCount },
  });
});

  1. Update API Gateway proxy rules if needed

  2. Document in API_DOCUMENTATION.md

  3. Add tests

Add New Feature to Mobile App

  1. Create feature directory:
mobile/flow_app/lib/features/your_feature/
├── models/
├── notifiers/
├── providers/
├── screens/
├── services/
└── widgets/
  1. Define route in core/router/app_router.dart:
GoRoute(
  path: '/your-feature',
  name: 'yourFeature',
  builder: (context, state) => const YourFeatureScreen(),
),
  1. Create screen:
// features/your_feature/screens/your_feature_screen.dart
class YourFeatureScreen extends ConsumerWidget {
  const YourFeatureScreen({Key? key}) : super(key: key);
 
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    return Scaffold(
      appBar: AppBar(title: const Text('Your Feature')),
      body: const Center(child: Text('Your Feature')),
    );
  }
}
  1. Add navigation from other screens

Seed Database with Test Data

# Supabase (PostgreSQL)
# Run database_seed.sql in Supabase SQL Editor
 
# Or use seed scripts
python seed_db.py
python seed_rest.py
 
# MongoDB
# Use seed scripts in each service
cd backend/user-service && npm run seed
cd backend/event-service && npm run seed

Troubleshooting

Port Already in Use

# Find process using port
# Windows
netstat -ano | findstr :3000
 
# macOS/Linux
lsof -i :3000
 
# Kill process
# Windows
taskkill /PID <PID> /F
 
# macOS/Linux
kill -9 <PID>

MongoDB Connection Failed

  1. Check MongoDB is running:

    # Docker
docker ps | grep mongo
 
# Local
# Windows
sc query MongoDB
 
# macOS
brew services list | grep mongodb

  2. Verify connection string in .env

  3. Check firewall settings

Supabase Connection Issues

  1. Verify credentials in .env.local
  2. Check Supabase project status
  3. Ensure RLS policies allow operations
  4. Check network connectivity

Flutter Build Errors

# Clean build
flutter clean
flutter pub get
 
# Update dependencies
flutter pub upgrade
 
# Rebuild
flutter build apk --debug

Next.js Build Failing

# Clear .next cache
rm -rf .next
 
# Clear node_modules
rm -rf node_modules package-lock.json
npm install
 
# Rebuild
npm run build

Best Practices

Security

  1. Never commit secrets to git
  2. Use environment variables for all configuration
  3. Validate all user input on backend
  4. Sanitize data before database operations
  5. Use HTTPS in production
  6. Implement rate limiting on all endpoints
  7. Keep dependencies updated regularly

Performance

  1. Minimize database queries (use joins, aggregations)
  2. Implement caching for frequently accessed data
  3. Use indexes on frequently queried fields
  4. Optimize images before upload
  5. Lazy load components and data
  6. Use pagination for large lists
  7. Monitor performance with profiling tools

Code Quality

  1. Write meaningful variable names
  2. Keep functions small and focused
  3. Add comments for complex logic
  4. Avoid code duplication (DRY principle)
  5. Handle errors gracefully
  6. Write tests for critical paths
  7. Document public APIs

Git Hygiene

  1. Commit often with clear messages
  2. Keep commits atomic (one logical change)
  3. Review your own code before PR
  4. Rebase instead of merge for clean history
  5. Delete merged branches
  6. Tag release versions

Additional Resources

Documentation

Tools

Community

  • GitHub Issues
  • GitHub Discussions
  • Team Slack/Discord

Happy Coding! 🚀

For deployment instructions, see Deployment Guide.

Graph View

Backlinks