ArchiTools/CLAUDE.md

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
State	localStorage (via StorageService abstraction)
Deploy	Docker multi-stage, Portainer, Nginx Proxy Manager
Repo	Gitea at http://10.10.10.166:3002/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 (localStorage default, designed for future DB/MinIO)
• Cross-module tagging system as shared service
• Auth stub designed for future Authentik SSO integration
• All entities include visibility / createdBy fields from day one

---

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 (13/13 — zero placeholders)

#	Module	Route	Key Features
1	Dashboard	/	Stats cards, module grid, external tools by category
2	Email Signature	/email-signature	Multi-company branding, live preview, zoom/copy/download
3	Word XML Generator	/word-xml	Category-based XML gen, simple/advanced mode, ZIP export
4	Registratura	/registratura	CRUD registry, stats, filters, legal deadline tracking
5	Tag Manager	/tag-manager	CRUD tags, category/scope/color, grouped display
6	IT Inventory	/it-inventory	Equipment tracking, type/status/company filters
7	Address Book	/address-book	CRUD contacts, card grid, search/type filter
8	Password Vault	/password-vault	CRUD credentials, show/hide/copy, category filter
9	Mini Utilities	/mini-utilities	Text case, char counter, percentage calc, area converter
10	Prompt Generator	/prompt-generator	Template-driven prompt builder, 4 builtin templates
11	Digital Signatures	/digital-signatures	CRUD signature/stamp/initials assets
12	Word Templates	/word-templates	Template library, 8 categories, version tracking
13	AI Chat	/ai-chat	Session-based chat UI, demo mode (no API keys yet)

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
Gitea	3002	Git hosting (gitadmin/ArchiTools)
Portainer	9000	Docker management, auto-deploy on push
Nginx Proxy Manager	81 (admin)	Reverse proxy + SSL termination
Uptime Kuma	3001	Service monitoring
MinIO	9003	Object storage (future)
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
Authentik	9100	SSO (future)

Deployment Pipeline

git push origin main
  → Gitea webhook fires
    → Portainer auto-redeploys stack
      → Docker multi-stage build (~1-2 min)
        → Container starts on :3000
          → Nginx Proxy Manager routes traffic

Docker

• Dockerfile: 3-stage build (deps → builder → runner), node:20-alpine, non-root user
• docker-compose.yml: single service, port 3000, watchtower label
• output: 'standalone' in next.config.ts is required

---

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

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

---

Future Integrations (not yet implemented)

Feature	Status	Notes
Authentik SSO	Auth stub exists	src/core/auth/ has types + provider shell
MinIO storage	Adapter pattern ready	Switch NEXT_PUBLIC_STORAGE_ADAPTER to minio
API backend	Adapter pattern ready	Switch to api adapter when backend exists
AI Chat API	UI complete, demo mode	No API keys yet; supports Claude/GPT/Ollama
N8N automations	Webhook URL configured	For notifications, backups, workflows

---

Model Recommendations for Tasks

Task Type	Recommended Model	Why
Bug fixes, small edits	Sonnet 4.5 or Haiku 4.5	Fast, cheap, good for focused changes
New module implementation	Opus 4.6	Complex architecture decisions, multi-file coordination
Refactoring	Sonnet 4.5	Good pattern recognition, thorough but faster than Opus
UI polish / styling	Sonnet 4.5	Tailwind expertise, fast iteration
Documentation	Sonnet 4.5	Clear writing, fast output
Complex business logic	Opus 4.6	Legal deadline logic, calendar math, chain workflows
Build/deploy debugging	Haiku 4.5	Quick diagnosis, low cost

Session Handoff Tips

• Read this CLAUDE.md first — it has all context
• 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
• 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