gitadmin/ArchiTools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d0b51be50a980c9c12f0dfde670d5531695ffcb5
ArchiTools/CLAUDE.md
T

19 KiB
Raw Blame History

ArchiTools — Project Context for AI Assistants

This file provides all context needed for Claude Code, Sonnet, or any AI model to work on this project from scratch.

Quick Start

npm install
npm run dev          # http://localhost:3000
npx next build       # verify zero errors before pushing
git push origin main # auto-deploys via Portainer webhook

Project Overview

ArchiTools is a modular internal web dashboard for an architecture/engineering office group of 3 companies:

  • Beletage (architecture)
  • Urban Switch (urbanism)
  • Studii de Teren (geotechnics)

It runs on an on-premise Ubuntu server at 10.10.10.166, containerized with Docker, managed via Portainer, served by Nginx Proxy Manager.

Stack

Layer Technology
Framework Next.js 16.x, App Router, TypeScript (strict)
Styling Tailwind CSS v4, shadcn/ui
Database PostgreSQL (10.10.10.166:5432) via Prisma v6 ORM
Storage DatabaseStorageAdapter (PostgreSQL) — localStorage fallback available
File Storage MinIO (10.10.10.166:9002 API / 9003 UI) — client configured, adapter pending
Auth NextAuth v4 + Authentik OIDC (auth.beletage.ro)
Deploy Docker multi-stage, Portainer CE, Nginx Proxy Manager
Repo Gitea at https://git.beletage.ro/gitadmin/ArchiTools
Language Code in English, UI in Romanian

Architecture Principles

  • Module platform, not monolith — each module isolated with own types/services/hooks/components
  • Feature flags gate module loading (disabled = zero bundle cost)
  • Storage abstraction: StorageService interface with adapters (database default via Prisma, localStorage fallback)
  • Cross-module tagging system as shared service
  • Auth via Authentik SSO — NextAuth v4 + OIDC, group→role/company mapping
  • All entities include visibility / createdBy fields from day one
  • Company logos — theme-aware (light/dark variants), dual-rendered for SSR safety

Repository Structure

src/
├── app/                        # Routing only (thin wrappers)
│   ├── (modules)/              # Module route pages
│   └── layout.tsx              # App shell
├── core/                       # Platform services
│   ├── module-registry/        # Module registration + types
│   ├── feature-flags/          # Flag evaluation + env override
│   ├── storage/                # StorageService + adapters
│   │   └── adapters/           # localStorage adapter (+ future DB/MinIO)
│   ├── tagging/                # Cross-module tag service
│   ├── i18n/                   # Romanian translations
│   ├── theme/                  # Light/dark theme
│   └── auth/                   # Auth types + stub (future Authentik)
├── modules/                    # Module business logic
│   ├── <module-name>/
│   │   ├── components/         # Module UI components
│   │   ├── hooks/              # Module-specific hooks
│   │   ├── services/           # Module business logic
│   │   ├── types.ts            # Module types
│   │   ├── config.ts           # Module metadata
│   │   └── index.ts            # Public exports
│   └── ...
├── shared/                     # Shared UI
│   ├── components/
│   │   ├── ui/                 # shadcn/ui primitives
│   │   ├── layout/             # Sidebar, Header
│   │   └── common/             # Reusable app components
│   ├── hooks/                  # Shared hooks
│   └── lib/                    # Utils (cn, etc.)
├── config/                     # Global config
│   ├── modules.ts              # Module registry entries
│   ├── flags.ts                # Default feature flags
│   ├── navigation.ts           # Sidebar nav structure
│   └── companies.ts            # Company definitions
docs/                           # 16 internal technical docs
legacy/                         # Original HTML tools for reference

Implemented Modules (14/14 — zero placeholders)

# Module Route Version Key Features
1 Dashboard / 0.1.0 KPI cards (6), activity feed (last 20), module grid, external tools
2 Email Signature /email-signature 0.1.0 Multi-company branding, address toggle (BTG/US/SDT), live preview, zoom/copy/download
3 Word XML Generator /word-xml 0.1.0 Category-based XML gen, simple/advanced mode, ZIP export
4 Registratura /registratura 0.2.0 CRUD registry, dynamic doc types, bidirectional Address Book, threads, backdating, legal deadline tracking, recipient registration, document expiry
5 Tag Manager /tag-manager 0.2.0 CRUD tags, category/scope/color, US/SDT seeds, mandatory categories, ManicTime bidirectional sync
6 IT Inventory /it-inventory 0.2.0 Dynamic equipment types, rented status (purple pulse), 42U rack visualization, type/status/company filters
7 Address Book /address-book 0.1.0 CRUD contacts, card grid, vCard export, Registratura reverse lookup, dynamic types (creatable)
8 Password Vault /password-vault 0.3.0 CRUD credentials, 9 categorii cu iconițe, WiFi QR code real, context-aware form, strength meter, company scope, AES-256-GCM encryption
9 Mini Utilities /mini-utilities 0.1.0 Text case, char counter, percentage, area converter, U→R, artifact cleaner, MDLPA, PDF reducer, OCR
10 Prompt Generator /prompt-generator 0.2.0 Template-driven prompt builder, 18 templates (14 text + 4 image), search bar, target type filter
11 Digital Signatures /digital-signatures 0.1.0 CRUD assets, drag-and-drop file upload, tag chips
12 Word Templates /word-templates 0.1.0 Template library, 8 categories, version tracking, .docx placeholder auto-detection
13 AI Chat /ai-chat 0.2.0 Multi-provider (OpenAI/Claude/Ollama/demo), project linking via Tag Manager, provider status badge
14 Hot Desk /hot-desk 0.1.0 4 desks, week-ahead calendar, room layout (window+door), reserve/cancel

Registratura — Legal Deadline Tracking (Termene Legale)

The Registratura module includes a full legal deadline tracking engine for Romanian construction permitting:

  • 16 deadline types across 5 categories (Avize, Completări, Analiză, Autorizare, Publicitate)
  • Working days vs calendar days with Romanian public holiday support (including Orthodox Easter via Meeus algorithm)
  • Backward deadlines (e.g., AC extension: 45 working days BEFORE expiry)
  • Chain deadlines (resolving one prompts adding the next)
  • Tacit approval (auto-detected when overdue + applicable type)
  • Tabbed UI: "Registru" tab (existing registry) + "Termene legale" tab (deadline dashboard)

Key files:

  • services/working-days.ts — Romanian holidays, addWorkingDays(), isWorkingDay()
  • services/deadline-catalog.ts — 16 DeadlineTypeDef entries
  • services/deadline-service.ts — createTrackedDeadline(), resolveDeadline(), aggregateDeadlines()
  • components/deadline-dashboard.tsx — Stats + filters + table
  • components/deadline-add-dialog.tsx — 3-step wizard (category → type → date preview)

Infrastructure

Server: 10.10.10.166 (Ubuntu)

Service Port Purpose
ArchiTools 3000 This app (tools.beletage.ro)
Gitea 3002 Git hosting (git.beletage.ro)
PostgreSQL 5432 App database (Prisma ORM)
Portainer 9000 Docker management
Nginx Proxy Manager 81 (admin) Reverse proxy + SSL termination
Uptime Kuma 3001 Service monitoring
MinIO 9002 (API) / 9003 (UI) Object storage
Authentik 9100 SSO (auth.beletage.ro) — active
N8N 5678 Workflow automation (future)
Stirling PDF 8087 PDF tools
IT-Tools 8085 Developer utilities
FileBrowser 8086 File management
Netdata 19999 System monitoring
Dozzle 9999 Docker log viewer
CrowdSec 8088 Security

Deployment Pipeline

git push origin main
  → Gitea webhook fires
    → Portainer CE detects new commit
      → Manual "Pull and redeploy" in Portainer (CE doesn't auto-rebuild)
        → Docker multi-stage build (~1-2 min)
          → Container starts on :3000
            → Nginx Proxy Manager routes to tools.beletage.ro

Docker

  • Dockerfile: 3-stage build (deps → builder → runner), node:20-alpine, non-root user
  • Dockerfile includes npx prisma generate before build step
  • docker-compose.yml: single service, port 3000, all env vars hardcoded (Portainer CE can't inject env vars)
  • output: 'standalone' in next.config.ts is required
  • @prisma/client must be in dependencies (not devDependencies) for runtime

Development Rules

TypeScript Strict Mode Gotchas

  • array.split()[0] returns string | undefined — use .slice(0, 10) instead
  • Record<string, T>[key] returns T | undefined — always guard with null check
  • Spread of possibly-undefined objects: { ...obj[key], field } — check existence first
  • lucide-react Icons: cast through unknown → React.ComponentType<{ className?: string }>

Conventions

  • Code: English
  • UI text: Romanian
  • Components: functional, 'use client' directive where needed
  • State: localStorage via useStorage('module-name') hook
  • IDs: uuid v4
  • Dates: ISO strings (YYYY-MM-DD for display, full ISO for timestamps)
  • No emojis in code or UI unless explicitly requested

Storage Performance Rules

  • NEVER use storage.list() followed by storage.get() in a loop — this is an N+1 query bug
  • list() fetches ALL items (keys+values) from DB but discards values, then each get() re-fetches individually
  • ALWAYS use storage.exportAll() (namespaced) or storage.export(namespace) (service-level) to batch-load
  • Filter items client-side after a single fetch: for (const [key, value] of Object.entries(all)) { ... }
  • After mutations (add/update), either do optimistic local state update or a single refresh() — never both
  • NEVER store large binary data (base64 files) inside entity JSON — this makes list loading transfer tens of MB
  • For modules with attachments: use exportAll({ lightweight: true }) for listing, storage.get() for single-entry full load
  • The API ?lightweight=true parameter strips data/fileData strings >1KB from JSON values server-side
  • Future: move file data to MinIO; only store metadata (name, size, type, url) in the entity JSON

Module Development Pattern

Every module follows:

src/modules/<name>/
├── components/     # React components
├── hooks/          # Custom hooks (use-<name>.ts)
├── services/       # Business logic (pure functions)
├── types.ts        # TypeScript interfaces
├── config.ts       # ModuleConfig metadata
└── index.ts        # Public exports

Before Pushing

  1. npx next build — must pass with zero errors
  2. Test the feature manually on localhost:3000
  3. Commit with descriptive message
  4. git push origin main — Portainer auto-deploys

Company IDs

ID Name Prefix
beletage Beletage B
urban-switch Urban Switch US
studii-de-teren Studii de Teren SDT
group Grup G

Current Integrations

Feature Status Notes
Authentik SSO ✅ Active NextAuth v4 + OIDC, group→role/company mapping
PostgreSQL ✅ Active Prisma ORM, KeyValueStore model, /api/storage route
MinIO Client configured 10.10.10.166:9002, bucket tools, adapter pending
AI Chat API ✅ Multi-provider /api/ai-chat — OpenAI/Claude/Ollama/demo; needs API key env
Vault Encryption ✅ Active AES-256-GCM server-side, /api/vault, ENCRYPTION_SECRET env
ManicTime Sync ✅ Implemented /api/manictime — bidirectional Tags.txt sync, needs SMB mount
N8N automations Webhook URL configured For notifications, backups, workflows

Model Recommendations

Task Type Claude OpenAI Google Notes
Bug fixes, config Haiku 4.5 GPT-4o-mini Gemini 2.5 Flash Fast, cheap
Features, tests, UI Sonnet 4.6 GPT-5.2 Gemini 3 Flash Best value — Opus-class quality at Sonnet price
New modules, architecture Opus 4.6 GPT-5.3-Codex Gemini 3 Pro Complex multi-file, business logic

Default: Sonnet 4.6 for most work. See ROADMAP.md for per-task recommendations.

Session Handoff Tips

  • Read this CLAUDE.md first — it has all context
  • Read ROADMAP.md for the complete task list with dependencies
  • Check docs/ for deep dives on specific systems
  • Check src/modules/<name>/types.ts before modifying any module
  • Always run npx next build before committing
  • Push to main → Portainer auto-deploys via Gitea webhook
  • The 16 docs in docs/ total ~10,600 lines — search them for architecture questions

Documentation Index

Doc Path Content
System Architecture docs/architecture/SYSTEM-ARCHITECTURE.md Overall architecture, module platform design
Module System docs/architecture/MODULE-SYSTEM.md Module registry, lifecycle, config format
Feature Flags docs/architecture/FEATURE-FLAGS.md Flag system, env overrides
Storage Layer docs/architecture/STORAGE-LAYER.md StorageService interface, adapters
Tagging System docs/architecture/TAGGING-SYSTEM.md Cross-module tags
Security & Roles docs/architecture/SECURITY-AND-ROLES.md Visibility, auth, roles
Module Dev Guide docs/guides/MODULE-DEVELOPMENT.md How to create a new module
HTML Integration docs/guides/HTML-TOOL-INTEGRATION.md Legacy tool migration
UI Design System docs/guides/UI-DESIGN-SYSTEM.md Design tokens, component patterns
Docker Deployment docs/guides/DOCKER-DEPLOYMENT.md Full Docker/Portainer/Nginx guide
Coding Standards docs/guides/CODING-STANDARDS.md TS strict, naming, patterns
Testing Strategy docs/guides/TESTING-STRATEGY.md Testing approach
Configuration docs/guides/CONFIGURATION.md Env vars, flags, companies
Data Model docs/DATA-MODEL.md All entity schemas
Repo Structure docs/REPO-STRUCTURE.md Directory layout
Prompt Generator docs/modules/PROMPT-GENERATOR.md Prompt module deep dive
Reference in New Issue View Git Blame Copy Permalink