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

```bash
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 |