# 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

**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.

---

### 1.02 `[STANDARD]` Email Signature — Address Toggle for US/SDT

**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`
**User action needed:** Confirm addresses for Urban Switch and Studii de Teren.

---

### 1.03 `[STANDARD]` Prompt Generator — Architecture Visualization Templates

**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)

---

### 1.04 `[STANDARD]` Tag Manager — US/SDT Project Seeds + Mandatory Categories

**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

---

### 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

---

### 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

---

### 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

---

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

---

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

---

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

---

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

---

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

**What:** The linked-entry selector in `registry-entry-form.tsx` shows only first 20 entries (`.slice(0, 20)`). Add a search/filter field to find entries by number or subject, and remove the 20 limit.
**Files to modify:** `src/modules/registratura/components/registry-entry-form.tsx`

---

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

**What:** The xlsx says POT/CUT auto-calculation is "not needed". The toggle exists but the auto-injection code in `xml-generator.ts` should be removed. Keep the fields, just remove the auto-compute logic.
**Files to modify:** `src/modules/word-xml/services/xml-generator.ts`
**User action needed:** Confirm this should be removed.

---

## 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