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

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.

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