ArchiTools/ROADMAP.md

# ArchiTools — Complete Roadmap

> Step-by-step implementation plan. Every task from `app_modules_overview.xlsx` is tracked here.
> Modules are implemented in dependency order, tested by the AI, then submitted for user approval.

---

## Workflow

1. AI picks the next task from this file (top to bottom)
2. AI implements it, runs `npx next build` (zero errors required)
3. AI commits and pushes to `main` (Portainer auto-deploys)
4. AI notifies you: "Module X / Task Y is ready for review"
5. You test on `http://10.10.10.166:3000` and approve or request changes
6. AI moves to the next task

---

## AI Model Recommendations

| Tag          | Claude     | OpenAI        | Google           | Best For                                                               |
| ------------ | ---------- | ------------- | ---------------- | ---------------------------------------------------------------------- |
| `[HEAVY]`    | Opus 4.6   | GPT-5.3-Codex | Gemini 3 Pro     | Complex multi-file features, business logic, architecture, new modules |
| `[STANDARD]` | Sonnet 4.6 | GPT-5.2       | Gemini 3 Flash   | Refactoring, moderate features, UI work, tests, documentation          |
| `[LIGHT]`    | Haiku 4.5  | GPT-4o-mini   | Gemini 2.5 Flash | Quick fixes, small edits, config changes, build debugging              |

**Default recommendation: Sonnet 4.6** — it matches Opus-class performance at Sonnet pricing ($3/$15 per M tokens). Use Opus only for tasks marked `[HEAVY]`. Use Haiku for tasks marked `[LIGHT]`.

---

## Current Module Status vs. XLSX Spec

| #   | Module             | Core Done   | Gaps Remaining                                                                   | New Features Needed                         |
| --- | ------------------ | ----------- | -------------------------------------------------------------------------------- | ------------------------------------------- |
| 1   | Registratura       | YES         | Linked-entry selector capped at 20                                               | Workflow automation, email integration, OCR |
| 2   | Email Signature    | YES         | US/SDT logo files may be missing from `/public/logos/`; US/SDT no address toggle | AD sync, branding packs                     |
| 3   | Word XML           | YES         | POT/CUT toggle exists (spec says remove)                                         | Schema validator, visual mapper             |
| 4   | Digital Signatures | YES         | No file upload (URL only); tags not editable in form                             | Permission layers, document insertion       |
| 5   | Password Vault     | YES         | Unencrypted storage; no strength meter; no company scope                         | Hardware key, rotation reminders            |
| 6   | IT Inventory       | YES         | assignedTo not linked to contacts; no maintenance log                            | Network scan import                         |
| 7   | Address Book       | YES         | No vCard export; no reverse Registratura lookup                                  | Email sync, deduplication                   |
| 8   | Prompt Generator   | YES         | Missing architecture viz templates (sketch→render, photorealism)                 | Prompt scoring                              |
| 9   | Word Templates     | YES         | No clause library; placeholders manual only; no Word generation                  | Diff compare, document generator            |
| 10  | Tag Manager        | YES         | No US/SDT project seeds; no mandatory-category enforcement                       | Server tag sync, smart suggestions          |
| 11  | Mini Utilities     | PARTIAL     | Missing: U→R value, AI artifact cleaner, MDLPA validator, PDF reducer, OCR       | More converters                             |
| 12  | Dashboard          | BASIC       | No activity feed, no notifications, no KPI panels                                | Custom dashboards per role                  |
| 13  | AI Chat            | DEMO ONLY   | No API integration, no key config, no streaming                                  | Conversation templates                      |
| 14  | Hot Desk           | NOT STARTED | Entire module missing                                                            | —                                           |

---

## PHASE 1 — Module Gap Fixes (close all xlsx gaps)

> Fix existing modules to match the xlsx spec. Ordered by impact and dependency.

### 1.01 ✅ `[LIGHT]` Verify Email Signature Logo Files (2026-02-18)

**What:** Check if `/public/logos/logo-us-dark.svg`, `logo-us-light.svg`, `logo-sdt-dark.svg`, `logo-sdt-light.svg` exist. If not, create placeholder SVGs or obtain real logos from the user.
**Files:** `public/logos/`
**Why first:** Broken images are the most visible bug.
**User action needed:** Provide actual logo files for Urban Switch and Studii de Teren if placeholders won't do.
**Status:** All logo files exist with valid SVG content. No action needed.

---

### 1.02 ✅ `[STANDARD]` Email Signature — Address Toggle for US/SDT (2026-02-18)

**What:** Urban Switch and Studii de Teren are hardcoded to Str. Unirii address. Add address toggle (like Beletage has) if these companies use different addresses.
**Files:** `src/modules/email-signature/components/signature-configurator.tsx`, `src/modules/email-signature/services/company-branding.ts`
**User action needed:** Confirm addresses for Urban Switch and Studii de Teren.
**Status:** Address toggle UI added for US and SDT companies. Currently configured with Str. Unirii address for both. User can update addresses in company-branding.ts when confirmed.

---

### 1.03 ✅ `[STANDARD]` Prompt Generator — Architecture Visualization Templates (2026-02-18)

**What:** Add 6+ new builtin templates per xlsx spec:

1. Architectural rendering prompt (basic massing to detailed)
2. Sketch → professional render prompt
3. Visualization refinement prompt (photorealism fine-tuning)
4. Technical compliance checking prompt
5. Legal/formal review prompt (extend existing)
6. Contract text cleanup prompt
7. GIS / survey interpretation prompt
8. BIM coordination prompt
9. Report rewriting prompt
10. Structured technical Q&A prompt

**Files to modify:** `src/modules/prompt-generator/services/builtin-templates.ts`
**Files to create:** Additional template definitions (can be in same file or split)
**Status:** 10 new templates added (total 14): arch-render-massing, sketch-to-render, photorealism-refinement, tech-compliance, legal-formal-review, contract-cleanup, gis-survey-interpretation, bim-coordination, report-rewrite, structured-qa.

---

### 1.04 ✅ `[STANDARD]` Tag Manager — US/SDT Project Seeds + Mandatory Categories (2026-02-18)

**What:**

1. Add Urban Switch and Studii de Teren project numbering to seed data (US-001, SDT-001 format)
2. Enforce mandatory 1st category (project) and 2nd category (phase) when creating tags — show validation error if missing
3. Import the full tag structure from `legacy/manicprojects/current manic time Tags.txt` in proper 1st→5th category hierarchy

**Files to modify:**

- `src/modules/tag-manager/services/seed-data.ts` — Add US/SDT projects
- `src/modules/tag-manager/components/tag-create-form.tsx` — Add mandatory validation

**Status:** US (10 projects, US-001→US-010, color #345476) and SDT (10 projects, SDT-001→SDT-010, color #0182A1) seed data added. Mandatory validation enforces project code + company scope for project tags. Validation errors shown inline. Legacy ManicTime import already covered all Beletage projects + phases + activities + doc types.

---

### ✅ 1.05 `[STANDARD]` Mini Utilities — Add Missing Tools

**What:** Add the 5 missing tools from xlsx:

1. **U-value → R-value converter** (R = 1/U, with material thickness input)
2. **AI artifact cleaner** (strip markdown formatting, fix encoding, remove prompt artifacts from pasted text)
3. **MDLPA date locale validator** (validate Romanian administrative dates against legal calendar)
4. **PDF reducer** (compress PDF via Stirling PDF API at http://10.10.10.166:8087, or client-side canvas compression for images)
5. **Quick OCR** (paste image → extract text; use Tesseract.js client-side or Stirling PDF OCR endpoint)

**Files to modify:** `src/modules/mini-utilities/components/mini-utilities-module.tsx`
**Dependencies:** `tesseract.js` (for OCR), possibly Stirling PDF API calls

**Status:** ✅ Done. All 5 tools implemented: U→R calculator (with Rsi/Rse/λ), AI artifact cleaner (markdown strip + encoding fix + typography normalise), MDLPA iframe embed, PDF reducer via Stirling PDF API with level selector, OCR via ocr.z.ai iframe. Build passes, pushed to main.

---

### ✅ 1.06 `[STANDARD]` Digital Signatures — File Upload + Tag Editing

**What:**

1. Add drag-and-drop / file picker for uploading signature/stamp images (convert to base64 on upload, like Registratura attachments)
2. Add tag input field to the asset form (tags field exists in type but form doesn't render it)

**Files to modify:**

- `src/modules/digital-signatures/components/` — asset form component

**Status:** ✅ Done. Drag-and-drop/click file picker cu preview base64 în `AssetForm` și `AddVersionForm`. Tags chip input (Enter/virgulă pentru adăugare, Backspace/X pentru ștergere). Build ok, pushat.

---

### ✅ 1.07 `[LIGHT]` Password Vault — Company Scope + Strength Meter

**What:**

1. Add `company` field to credential type and form (scope passwords to a company)
2. Add password strength indicator (visual bar: weak/medium/strong based on length + character diversity)
3. Rename `encryptedPassword` → `password` in the type (it's not encrypted, the name is misleading)

**Files to modify:**

- `src/modules/password-vault/types.ts`
- `src/modules/password-vault/components/` — form and list components

**Status:** ✅ Done. Renamed `encryptedPassword` → `password` in type. Added `company: CompanyId` field. Form now has company selector (Beletage/Urban Switch/Studii/Grup). Password strength meter with 4 levels (slabă/medie/puternică/foarte puternică) based on length + character diversity (upper/lower/digit/symbol). Meter updates live. Build ok, pushat.

### ✅ 1.08 `[LIGHT]` IT Inventory — Link assignedTo to Address Book

**What:** Change `assignedTo` from free text to an autocomplete that links to Address Book contacts (same pattern as Registratura sender/recipient).
**Files to modify:**

- `src/modules/it-inventory/components/` — equipment form
- `src/modules/it-inventory/types.ts` — Add `assignedToContactId?: string`

**Status:** ✅ Done. Added `assignedToContactId?: string` field to InventoryItem type. Form now shows autocomplete dropdown filtering Address Book contacts (searches by name or company). Up to 5 suggestions shown. Clicking a contact pre-fills both display name and contact ID. Placeholder "Caută după nume..." guides users. Build ok, pushed.

---

### ✅ 1.09 `[STANDARD]` Address Book — vCard Export + Registratura Reverse Lookup

**What:**

1. Add "Export vCard" button per contact (generate `.vcf` file download)
2. Add a section showing Registratura entries where this contact appears as sender or recipient

**Files to modify:**

- `src/modules/address-book/components/` — contact card/detail view
  **Files to create:**
- `src/modules/address-book/services/vcard-export.ts`

**Status:** ✅ Done. Created `vcard-export.ts` generating vCard 3.0 (.vcf) with name, org, title, phones, emails, address, website, notes, contact persons. Added Download icon button on card hover. Added detail dialog (FileText icon) showing full contact info + scrollable table of all Registratura entries where this contact appears as sender or recipient (uses `allEntries` to bypass filters). Build ok, pushed.

### ✅ 1.10 `[STANDARD]` Word Templates — Placeholder Auto-Detection

**What:** When a template file URL points to a `.docx`, parse it client-side to extract `{{placeholder}}` patterns and auto-populate the `placeholders[]` field. Use JSZip (already installed) to read the docx XML.
**Files to modify:**

- `src/modules/word-templates/components/` — template form
  **Files to create:**
- `src/modules/word-templates/services/placeholder-parser.ts`

**Status:** ✅ Done. `placeholder-parser.ts` uses JSZip to read all `word/*.xml` files from the .docx ZIP, searches for `{{...}}` patterns in both raw XML and stripped text (handles Word’s split-run encoding). Form now has: “Alege fișier .docx” button (local file picker, most reliable — no CORS) and a Wand icon on the URL field for URL-based detection (may fail on CORS). Parsing spinner shown during detection. Detected placeholders auto-populate the field. Build ok, pushed.

### ✅ 1.11 `[STANDARD]` Dashboard — Activity Feed + KPI Panels

**What:**

1. Add an activity feed showing recent actions across modules (last 20 creates/updates/deletes from localStorage timestamps)
2. Add KPI cards: entries this week, deadlines this week, overdue count, contacts added this month
3. Wire the `DashboardWidget` type that already exists in `types.ts`

**Files to modify:** `src/modules/dashboard/components/` or `src/app/(modules)/page.tsx`

**Status:** ✅ Done. Created `src/modules/dashboard/hooks/use-dashboard-data.ts` — scans all `architools:*` localStorage keys directly, extracts entities with timestamps, builds activity feed (last 20, sorted by `updatedAt`) and KPI counters. Updated `src/app/page.tsx`: KPI grid (6 cards: registratura this week, open dosare, deadlines this week, overdue in red, new contacts this month, active IT equipment), activity feed with module icon + label + action + relative time (Romanian locale). Build ok, pushed.

---

### ✅ 1.12 `[LIGHT]` Registratura — Increase Linked-Entry Selector Limit

**What:** Added search/filter input (by number, subject, sender) to the linked-entry selector. Removed `.slice(0, 20)` cap. Also improved chip labels to show truncated subject.
**Commit:** `cd4b0de`
**Status:** Done ✅

---

### ✅ 1.13 `[LIGHT]` Word XML — Remove POT/CUT Auto-Calculation

**What:** Removed `computeMetrics` entirely from `XmlGeneratorConfig`, `generateCategoryXml`, `generateAllCategories`, `downloadZipAll`, `useXmlConfig`, `XmlSettings`, and `WordXmlModule`. Fields kept; auto-injection removed.
**Commit:** `eaca24a`
**Status:** Done ✅

---

## PHASE 2 — New Module: Hot Desk Management

> Module 14 from xlsx. Entirely new.

### 2.01 `[HEAVY]` Hot Desk Module — Full Implementation

**What:** Build Module 14 from scratch per xlsx spec:

- 4 desks in a shared room
- Users reserve desks 1 week ahead
- Calendar view showing desk availability per day
- Reserve/cancel actions
- History of past reservations
- Visual room layout showing which desks are booked

**Module structure:**

```
src/modules/hot-desk/
├── components/
│   ├── hot-desk-module.tsx      # Main view with calendar + room layout
│   ├── desk-calendar.tsx        # Week view with 4 desk columns
│   ├── desk-room-layout.tsx     # Visual 4-desk room diagram
│   └── reservation-dialog.tsx   # Book/cancel dialog
├── hooks/
│   └── use-reservations.ts      # CRUD + conflict detection
├── services/
│   └── reservation-service.ts   # Business logic, overlap check
├── types.ts                     # DeskReservation, DeskId
├── config.ts                    # Module metadata
└── index.ts
```

**Files to also create/modify:**

- `src/app/(modules)/hot-desk/page.tsx` — Route
- `src/config/modules.ts` — Register module
- `src/config/navigation.ts` — Add sidebar entry
- `src/config/flags.ts` — Add feature flag

**User approval required** before moving to Phase 3.

---

## PHASE 3 — Quality & Testing

> Foundation work: tests, CI, docs, data safety.

### 3.01 `[STANDARD]` Install Testing Framework (Vitest)

**What:** Install and configure Vitest with React Testing Library.

```bash
npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom @vitest/coverage-v8
```

**Files to create:** `vitest.config.ts`, `src/test-setup.ts`
**Files to modify:** `package.json` (add test scripts)

---

### 3.02 `[STANDARD]` Unit Tests — Critical Services

**What:** Write tests for the most critical business logic:

1. `working-days.test.ts` — Orthodox Easter 2024-2030, addWorkingDays, backward deadlines
2. `deadline-service.test.ts` — Due date computation, tacit approval, chain resolution
3. `registry-service.test.ts` — Number generation, overdue calculation
4. `local-storage.test.ts` — CRUD, namespace isolation
5. `feature-flags.test.ts` — Defaults, env overrides

**Coverage target:** 90%+ for services.

---

### 3.03 `[STANDARD]` Data Export/Import for All Modules

**What:** Create a shared utility for backing up localStorage data:

1. Per-module JSON export (download file)
2. Per-module JSON import (upload + merge)
3. Full backup: export ALL modules as single JSON
4. Add export/import buttons to each module's main view

**Files to create:** `src/shared/hooks/use-data-export.ts`, `src/shared/components/common/data-export-button.tsx`

---

### 3.04 `[LIGHT]` Update Stale Documentation

**What:** Update docs to reflect current state:

- `docs/architecture/SYSTEM-ARCHITECTURE.md` — Change modules from "Planned" to "Implemented"
- `docs/DATA-MODEL.md` — Add TrackedDeadline, Hot Desk schemas
- `docs/REPO-STRUCTURE.md` — Add new files

---

### 3.05 `[LIGHT]` Wire External Tool URLs to Env Vars

**What:** `src/config/external-tools.ts` has hardcoded IPs. Wire to `process.env.NEXT_PUBLIC_*_URL` with fallback.

---

## PHASE 4 — AI Chat Integration

> Make Module 13 functional.

### 4.01 `[HEAVY]` AI Chat — Real API Integration

**What:** Replace demo mode with actual AI provider calls:

- Create `/api/ai/chat` server-side route (API keys never exposed to browser)
- Provider abstraction: Anthropic Claude, OpenAI GPT, Ollama (local)
- Response streaming via ReadableStream
- Model selector in the UI
- Token usage display

**Env vars:**

```
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OLLAMA_BASE_URL=http://10.10.10.166:11434
AI_DEFAULT_PROVIDER=anthropic
AI_DEFAULT_MODEL=claude-sonnet-4-6-20261001
```

**User action needed:** Provide API keys when ready.

---

### 4.02 `[STANDARD]` AI Chat — Domain-Specific System Prompts

**What:** Architecture office-focused conversation modes:

- Romanian construction law assistant
- Architectural visualization prompt crafter
- Technical specification writer
- Urban planning regulation lookup
- Document drafting assistant
- Normative compliance checker

---

### 4.03 `[LIGHT]` Enable AI Chat Feature Flag

**What:** Set `module.ai-chat` enabled in `flags.ts` + production `.env`.

---

## PHASE 5 — Authentication (Authentik SSO)

> Real users, real permissions. Requires server admin access.

### 5.01 `[HEAVY]` Authentik OIDC Integration

**What:** Replace stub user with real Authentik SSO.

- NextAuth.js / Auth.js route handler
- OIDC token → user profile resolution
- Cookie-based session
- `useAuth()` returns real user

**Server setup required:**

1. Create OAuth2 app in Authentik (http://10.10.10.166:9100)
2. Set redirect URI: `http://10.10.10.166:3000/api/auth/callback/authentik`
3. Set env vars: `AUTHENTIK_URL`, `AUTHENTIK_CLIENT_ID`, `AUTHENTIK_CLIENT_SECRET`, `NEXTAUTH_SECRET`

**User action needed:** Authentik admin credentials.

---

### 5.02 `[STANDARD]` Module-Level Access Control

**What:** Implement `canAccessModule()` with role-based rules. FeatureGate checks flag + permission.
**Depends on:** 5.01

---

### 5.03 `[STANDARD]` Data Visibility Enforcement

**What:** Filter storage results by `visibility` and `createdBy` fields (already stored on every entity, never enforced).
**Depends on:** 5.01

---

### 5.04 `[LIGHT]` Audit Logging

**What:** Log create/update/delete actions with user ID + timestamp. Console initially, later storage/N8N.
**Depends on:** 5.01

---

## PHASE 6 — Storage Migration (localStorage → Database)

> Multi-user shared data. Requires PostgreSQL + infrastructure changes.

### 6.01 `[HEAVY]` PostgreSQL + Prisma Setup

**What:** Add PostgreSQL container, create Prisma schema for all entities, run migrations.
**Infrastructure:** New `postgres` service in `docker-compose.yml`.

---

### 6.02 `[HEAVY]` API Storage Adapter

**What:** Create `ApiStorageAdapter` implementing `StorageService`. Use Next.js API routes + Prisma.
**Depends on:** 6.01

---

### 6.03 `[STANDARD]` Data Migration Tool

**What:** One-time export from localStorage → import to PostgreSQL. Preserve IDs and timestamps.
**Depends on:** 6.02

---

### 6.04 `[HEAVY]` MinIO File Storage

**What:** Create `MinioAdapter` for file uploads. Migrate base64 attachments to MinIO objects.
**MinIO already running** at http://10.10.10.166:9003.
**User action needed:** MinIO access key + secret key.

---

## PHASE 7 — Advanced Features

> Cross-cutting features that enhance the entire platform.

### 7.01 `[HEAVY]` Project Entity & Cross-Module Linking

**What:** New module: Projects. Central entity linking Registratura entries, Tags, Contacts, Templates.
**Reference:** `docs/DATA-MODEL.md` lines 566-582.

---

### 7.02 `[STANDARD]` Global Search (Cmd+K)

**What:** Search across all modules. Each module registers a search provider. Header bar integration.

---

### 7.03 `[STANDARD]` Notification System

**What:** Bell icon in header. Deadline alerts, overdue warnings, tacit approval triggers.

---

### 7.04 `[STANDARD]` Registratura — Print/PDF Export

**What:** Export registry as formatted PDF. Options: full registry, single entry, deadline summary.

---

### 7.05 `[STANDARD]` Word Templates — Clause Library + Document Generator

**What:** In-app clause composition, template preview, simple Word generation from templates.

---

### 7.06 `[STANDARD]` N8N Webhook Integration

**What:** Fire webhooks on events (new entry, deadline approaching, status change). N8N at http://10.10.10.166:5678.

---

### 7.07 `[STANDARD]` Mobile Responsiveness Audit

**What:** Test all modules on 375px/768px. Fix overflowing tables, forms, sidebar.

---

## PHASE 8 — Security & External Access

### 8.01 `[HEAVY]` Guest/External Access Role

**What:** Read-only guest role, time-limited share links. Depends on Authentik (Phase 5).

---

### 8.02 `[STANDARD]` CrowdSec Integration

**What:** IP banning for brute force. CrowdSec at http://10.10.10.166:8088.

---

### 8.03 `[LIGHT]` SSL/TLS via Let's Encrypt

**What:** When public domain ready, configure in Nginx Proxy Manager.

---

## PHASE 9 — CI/CD

### 9.01 `[STANDARD]` Gitea Actions CI Pipeline

**What:** `.gitea/workflows/ci.yml` — lint, typecheck, test, build on push.
**Check first:** Is Gitea Actions runner installed on server?

---

### 9.02 `[STANDARD]` E2E Tests (Playwright)

**What:** End-to-end tests for critical flows: navigation, Registratura CRUD, email signature, tag management.

---

## Infrastructure Credentials Needed

| Service                  | What                                    | When Needed         |
| ------------------------ | --------------------------------------- | ------------------- |
| **US/SDT Logos**         | SVG/PNG logo files                      | Phase 1 (task 1.01) |
| **US/SDT Addresses**     | Office addresses for email signature    | Phase 1 (task 1.02) |
| **Anthropic API Key**    | `sk-ant-...` from console.anthropic.com | Phase 4 (task 4.01) |
| **OpenAI API Key**       | `sk-...` from platform.openai.com       | Phase 4 (task 4.01) |
| **Authentik Admin**      | Login to create OAuth app at :9100      | Phase 5 (task 5.01) |
| **MinIO Credentials**    | Access key + secret key for :9003       | Phase 6 (task 6.04) |
| **PostgreSQL**           | New container + password                | Phase 6 (task 6.01) |
| **Gitea Actions Runner** | Registration token from Gitea admin     | Phase 9 (task 9.01) |

---

## Quick Picker

**15 min tasks** `[LIGHT]`:

- 1.01 — Check logo files
- ~~1.07 — Password vault company + strength~~ ✅
- 1.08 — IT inventory contact link
- 1.12 — Registry linked-entry limit
- 1.13 — Remove POT/CUT auto-calc
- 3.04 — Update stale docs
- 3.05 — Wire env var URLs

**1 hour tasks** `[STANDARD]`:

- 1.03 — Prompt generator templates
- 1.04 — Tag manager seeds + mandatory
- ~~1.05 — Mini utilities new tools~~ ✅
- ~~1.06 — Digital signatures upload~~ ✅
- 1.09 — Address book vCard + reverse lookup
- 1.11 — Dashboard activity feed + KPIs
- 3.01 + 3.02 — Tests setup + core tests

**Full session tasks** `[HEAVY]`:

- 2.01 — Hot Desk module (new)
- 4.01 — AI Chat API integration
- 5.01 — Authentik SSO
- 6.01 + 6.02 — PostgreSQL + API adapter
- 7.01 — Project entity module