grabbit/meteor_detection_system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
meteor_detection_system/CLAUDE.md
grabbit d272a38247 polish frontend
2025-08-11 19:04:26 +08:00

7.0 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Architecture

This is a distributed meteor monitoring network with a microservices architecture:

Core Services

  • meteor-frontend/ - Next.js 15 frontend with React 19, TypeScript, TailwindCSS 4, and React Query
  • meteor-web-backend/ - NestJS backend API with PostgreSQL, TypeORM, JWT auth, and Stripe payments
  • meteor-compute-service/ - Go microservice for event processing with AWS SDK and PostgreSQL
  • meteor-edge-client/ - Rust edge client for Raspberry Pi devices with camera integration

Key Technologies

  • Frontend: Next.js 15, React 19, TypeScript, TailwindCSS 4, React Query, React Hook Form, Recharts
  • Backend: NestJS, TypeORM, PostgreSQL, JWT, Stripe, AWS SDK (S3, SQS, CloudWatch), Pino logging
  • Processing: Go 1.24, PostgreSQL (pgx), AWS SDK, structured logging
  • Edge: Rust, Tokio, Serde, Reqwest, OpenCV (optional), cross-compilation for ARM64

Development Commands

Full Stack Development

# Start all services (frontend + backend)
npm run dev

# Start individual services
npm run dev:frontend    # Next.js on port 3000
npm run dev:backend     # NestJS on port 3000 (with CORS for frontend)

Building

npm run build           # Build all services
npm run build:frontend  # Build Next.js app
npm run build:backend   # Build NestJS app

Testing

# Complete test suite
npm run test:fullstack  # All tests: unit + integration + e2e

# Individual test types
npm run test            # Unit tests for both frontend and backend
npm run test:frontend   # Jest tests for React components
npm run test:backend    # Jest tests for NestJS services
npm run test:e2e        # Playwright E2E tests
npm run test:integration # Backend integration tests with real DB

# Test setup and teardown
./test-setup.sh         # Initialize test environment with Docker
npm run setup:test      # Alternative test setup command
npm run clean:test      # Clean up test containers

Linting

npm run lint            # Lint all code
npm run lint:frontend   # Next.js ESLint
npm run lint:backend    # NestJS ESLint with Prettier

Database Operations (Backend)

cd meteor-web-backend
npm run migrate:up      # Run pending migrations
npm run migrate:down    # Rollback last migration
npm run migrate:create <name>  # Create new migration

Edge Client (Rust)

cd meteor-edge-client
cargo build --release                           # Native build
cargo build --target=aarch64-unknown-linux-gnu # ARM64 build for Pi
./build.sh                                      # Cross-compile for Raspberry Pi
./demo_integration_test.sh                      # Integration test

Database Architecture

Entity Relationships

  • Users: UserProfile + UserIdentity (supports multiple auth methods)
  • Devices: Device + InventoryDevice (ownership tracking)
  • Events: RawEvent → ValidatedEvent (processing pipeline)
  • Analysis: AnalysisResult (AI/ML analysis data)
  • Weather: WeatherStation + WeatherObservation + WeatherForecast
  • Camera: CameraDevice (hardware management)
  • Subscriptions: SubscriptionPlan + UserSubscription + SubscriptionHistory + PaymentRecord

Migration System

  • Uses node-pg-migrate for schema management
  • All entities defined in meteor-web-backend/src/entities/
  • Migrations in meteor-web-backend/migrations/

Authentication & Authorization

JWT-based Authentication

  • Login/Register endpoints in AuthController
  • JWT strategy with passport-jwt
  • Subscription-based authorization via SubscriptionGuard
  • Password hashing with bcrypt

API Structure

  • Base path: /api/v1/
  • Protected routes require Bearer token
  • CORS enabled for localhost:3000 (frontend)

Event Processing Pipeline

Data Flow

  1. Edge Client (Rust) captures meteor events via camera
  2. Raw Event Upload to backend API with media files
  3. SQS Queue triggers processing in Go compute service
  4. Validation using MVP or Classical CV providers
  5. Analysis Results stored and exposed via API
  6. Frontend Gallery displays validated events with infinite scroll

File Storage

  • AWS S3 for media storage (images/videos)
  • LocalStack for development/testing
  • Multipart upload support in backend

Testing Architecture

Three-Layer Testing

  1. Unit Tests: Jest for both frontend and backend components
  2. Integration Tests: Full API workflows with test database
  3. E2E Tests: Playwright for user interactions

Test Environment

  • Docker Compose setup with test services
  • Separate PostgreSQL instance (port 5433)
  • LocalStack for AWS service mocking
  • Test data generation scripts

Gallery Testing

  • Complete E2E coverage for authentication, infinite scroll, responsive design
  • Integration tests for upload → processing → display workflow
  • Performance testing with large datasets

Frontend Architecture

Next.js App Router Structure

  • Pages in src/app/ (gallery, dashboard, settings, etc.)
  • Components organized by domain (auth/, gallery/, charts/, ui/)
  • React Query for server state management
  • Context-based auth state management

UI Components

  • Custom UI components in components/ui/
  • Chart components using Recharts
  • Form handling with React Hook Form + Zod validation
  • Responsive design with TailwindCSS 4

Backend Architecture

NestJS Module Structure

  • Domain-driven modules: Auth, Devices, Events, Payments, etc.
  • TypeORM entities with PostgreSQL
  • Structured logging with Pino
  • Prometheus metrics collection
  • Health checks and observability

Key Services

  • EventsService: Core event processing and pagination
  • AuthService: JWT token management and user validation
  • PaymentsService: Stripe integration for subscriptions
  • AnalysisService: AI/ML result processing
  • WeatherService: Environmental data correlation

Development Workflow

Adding New Features

  1. Create/update database entities and migrations
  2. Implement backend service and controller with tests
  3. Add frontend components and API integration
  4. Update E2E tests for user workflows
  5. Run full test suite before committing

Running Single Tests

# Backend unit test for specific service
cd meteor-web-backend && npm test -- --testPathPattern=events.service

# Frontend component test
cd meteor-frontend && npm test -- --testPathPattern=gallery

# Single E2E test
cd meteor-frontend && npx playwright test --grep="Gallery page"

# Integration test for specific feature
cd meteor-web-backend && npm run test:integration -- --testPathPattern=events

Production Deployment

Docker Support

  • Dockerfiles for all services
  • Next.js standalone output mode
  • Multi-stage builds for optimization

Infrastructure

  • Terraform configurations in infrastructure/
  • AWS services: RDS, S3, SQS, CloudWatch
  • Environment-based configuration

Observability

  • Structured JSON logging throughout stack
  • Metrics collection with Prometheus
  • Health check endpoints
  • Correlation IDs for request tracking