GeoShare/AGENTS.md

AGENTS.md - Family Safety Tracker

Overview

Dart server app (Shelf + PostgreSQL) for sharing geolocation with family members. REST API with JWT auth, bcrypt password hashing, and auto-expiring position data.

Quick Start

dart pub get
dart run bin/server.dart

Server starts on port 8080 (override with PORT env var).

Code Structure

• bin/ - All application code lives here (not lib/, which is empty).
  • bin/server.dart - Entry point. Starts Shelf server, database connection, and cleanup timer.
  • bin/routes/ - Route handlers (auth_routes.dart, user_routes.dart, geo_routes.dart)
  • bin/repositories/ - Data access layer (user_repo.dart, geoposition_repo.dart)
  • bin/models/ - Domain models (user.dart, geoposition.dart, log.dart)
  • bin/database/ - Database connection and auto-migration
• lib/ - Empty scaffold directory (stale, can be ignored).

Database

• PostgreSQL with connection via environment variables (POSTGRES_HOST, POSTGRES_DB, etc.) or defaults.
• Auto-migration: Tables are created on startup via Database.initialize(). No manual migration needed.
• Tables: users, geopositions, logs.

Runtime Behavior

• Expired geopositions are cleaned up every 5 minutes by a periodic timer in server.dart.
• Share links use UUIDs stored in-memory via GeopositionRepository.

API Endpoints

• POST /login - Authenticate with login/password, returns user data.
• /user - CRUD for users.
• /geo - POST to create position, UPDATE to update (with lifetime expiry).
• GET /watch?unique_id=... - Returns latest position for a share link.
• /share - Creates a one-time share link UUID.

Testing

dart test

Tests spawn the server process and hit endpoints. Server listens on port 8080 by default.

Build/Quality Commands

dart analyze          # Static analysis (uses analysis_options.yaml)
dart format --set .   # Format code

Dependencies

• shelf, shelf_router - HTTP framework
• postgres - PostgreSQL driver
• bcrypt - Password hashing
• dart_jsonwebtoken - JWT tokens
• dotenv - Environment config
• uuid - UUID generation

Notes

• SDK: ^3.10.1
• No Docker setup present (.dockerignore exists but no Dockerfile).
• Documentation in README.md is in Russian; the API is designed for geolocation sharing between family members.
• test_bcrypt.dart is a standalone test file, not part of the test suite.