From 34e45c6dea2ecf6660df6be10c0d9303909202b4 Mon Sep 17 00:00:00 2001 From: Anton Tranelis <31516529+antontranelis@users.noreply.github.com> Date: Thu, 14 Aug 2025 11:16:19 +0200 Subject: [PATCH] feat(other): add development configuration files (#307) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: add development configuration files Add .gitignore and CLAUDE.md to standardize development environment: - .gitignore: Exclude IDE files, build artifacts, and temporary files - CLAUDE.md: Project documentation and development commands for AI tools 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude * moved scripts to ./claude --------- Co-authored-by: Claude --- .gitignore | 3 +- CLAUDE.md | 125 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index adbb97d2..f767c892 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -data/ \ No newline at end of file +.claude/ +data/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..2400ceba --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,125 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +This is **Utopia Map**, a flexible collaborative mapping application for decentralized coordination and real-life networking. The project consists of three main parts: + +- **`/app`**: React application (frontend) - the main Utopia Map instance +- **`/lib`**: React component library (`utopia-ui`) - reusable UI components +- **`/backend`**: Directus CMS backend configuration and Docker setup + +## Development Commands + +### App (Frontend) +```bash +cd app +npm install +npm run dev # Start development server +npm run build # Build for production +npm run test:lint:eslint # Run ESLint +npm run preview # Preview production build +``` + +### Library (utopia-ui) +```bash +cd lib +npm install +npm run build # Build library +npm run start # Build in watch mode +npm run test:lint:eslint # Run ESLint +npm run lint # Run ESLint (alias) +npm run lintfix # Auto-fix ESLint issues +npm run test:component # Run Cypress component tests +npm run test:unit # Run Vitest unit tests with coverage +npm run test:unit:dev # Run Vitest in watch mode +npm run docs:generate # Generate TypeDoc documentation +``` + +### Root Level +```bash +./scripts/check-lint.sh # Run linting on both app and lib (used by PR hooks) +``` + +### Backend (Directus) +```bash +cd app +docker-compose up # Start Directus backend locally + +# Sync data to/from Directus (run from backend/) +npx directus-sync pull --directus-url http://localhost:8055 --directus-email admin@it4c.dev --directus-password admin123 +npx directus-sync push --directus-url http://localhost:8055 --directus-email admin@it4c.dev --directus-password admin123 +``` + +## Architecture Overview + +### High-Level Structure + +**Utopia Map** is built on a **3-tier monorepo architecture**: + +1. **Frontend App** (`/app`): Consumer application using `utopia-ui` components +2. **Component Library** (`/lib`): Reusable React components with TypeScript +3. **Backend** (`/backend`): Directus headless CMS with Docker configuration + +### Key Design Patterns + +**API Abstraction Layer**: The app uses API classes (`itemsApi`, `mapApi`, `layersApi`, etc.) that implement TypeScript interfaces to abstract backend communication. This allows swapping backends without changing components. + +**Layer-Based Data Model**: Items are organized into customizable **Layers** (e.g., Places, Projects, People) where each layer defines: +- Visual styling (icons, colors, markers) +- Data structure and validation +- Custom popup and profile templates + +**Component Composition**: The `UtopiaMap` component accepts child components like ``, ``, and `` to configure its behavior declaratively. + +**Type-Safe APIs**: All API interactions use TypeScript interfaces (`ItemsApi`, `UserApi`, `InviteApi`) ensuring type safety across the frontend-backend boundary. + +### Core Components Architecture + +- **`UtopiaMap`**: Main map container with Leaflet integration +- **`Layer`**: Defines item types with custom styling and behavior +- **`AppShell`**: Navigation, sidebar, and global app state management +- **`AuthProvider`**: Authentication context and user management +- **Profile Templates**: Flexible system for custom item display (`SimpleView`, `TabsView`, `OnepagerView`) + +### Data Flow + +1. **Items** are fetched via API classes from Directus backend +2. **Layers** define how items are displayed on the map +3. **Popups** show item previews when clicking map markers +4. **Profiles** provide detailed item views with custom templates +5. **Permissions** control CRUD operations based on user roles + +### Testing Strategy + +- **Unit Tests**: Vitest for lib components with coverage reporting +- **Component Tests**: Cypress for React component integration +- **Linting**: ESLint with TypeScript rules for code quality +- **Type Checking**: TypeScript strict mode across all packages + +### Import Conventions + +The lib uses path mapping for clean imports: +- `#components/*` → `./src/Components/*` +- `#types/*` → `./src/types/*` +- `#utils/*` → `./src/Utils/*` +- `#assets/*` → `./src/assets/*` + +### Backend Integration + +Uses **Directus** as headless CMS with: +- RESTful API for CRUD operations +- GraphQL endpoint available +- Real-time updates via WebSocket +- File/media management +- Role-based permissions +- Collection definitions in `/backend/directus-config/` + +## Code Quality + +- **ESLint** enforces code style across both app and lib +- **TypeScript strict mode** ensures type safety +- Pre-commit hooks run linting checks via `scripts/check-lint.sh` +- Coverage reporting for unit tests +- Automated dependency updates via `npm-check-updates` \ No newline at end of file