From b1df15bb42af7d2af9affbb55219fe88a5d8e185 Mon Sep 17 00:00:00 2001 From: Marius Tarau Date: Wed, 18 Feb 2026 18:06:18 +0200 Subject: [PATCH] docs: rewrite ROADMAP.md with complete xlsx gap analysis + multi-model recommendations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 9 phases, 35+ tasks covering all xlsx gaps and future features - Module 14 (Hot Desk) added as new module task - All gaps from app_modules_overview.xlsx tracked per module - Model recommendations: Claude (Opus/Sonnet 4.6/Haiku), OpenAI (GPT-5.3-Codex/5.2/4o-mini), Google (Gemini 3 Pro/Flash/2.5 Flash) - Step-by-step workflow: AI implements → builds → pushes → user approves - Quick picker by time budget (15min / 1hr / full session) - Infrastructure credentials checklist - Updated CLAUDE.md model table Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 20 +- ROADMAP.md | 877 +++++++++++++++++++++++++---------------------------- 2 files changed, 425 insertions(+), 472 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e5f6a64..93597b2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -223,23 +223,23 @@ src/modules// --- -## Model Recommendations for Tasks +## Model Recommendations -| 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 | +| Task Type | Claude | OpenAI | Google | Notes | +|---|---|---|---|---| +| **Bug fixes, config** | Haiku 4.5 | GPT-4o-mini | Gemini 2.5 Flash | Fast, cheap | +| **Features, tests, UI** | **Sonnet 4.6** | GPT-5.2 | Gemini 3 Flash | Best value — Opus-class quality at Sonnet price | +| **New modules, architecture** | Opus 4.6 | GPT-5.3-Codex | Gemini 3 Pro | Complex multi-file, business logic | + +**Default: Sonnet 4.6** for most work. See `ROADMAP.md` for per-task recommendations. ### Session Handoff Tips - Read this `CLAUDE.md` first — it has all context +- Read `ROADMAP.md` for the complete task list with dependencies - Check `docs/` for deep dives on specific systems - Check `src/modules//types.ts` before modifying any module - Always run `npx next build` before committing +- Push to `main` → Portainer auto-deploys via Gitea webhook - The 16 docs in `docs/` total ~10,600 lines — search them for architecture questions --- diff --git a/ROADMAP.md b/ROADMAP.md index 0375297..7b8f3bc 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,585 +1,538 @@ -# ArchiTools — Roadmap & Future Tasks +# ArchiTools — Complete Roadmap -> Detailed task list for continuing ArchiTools development. Each phase is ordered by priority and dependency. Tasks include recommended AI model, estimated complexity, and file references. +> 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. --- -## How to Use This File +## Workflow -1. **Pick a phase** — phases are ordered by priority (Phase 1 first) -2. **Pick a task** — tasks within a phase are ordered by dependency (earlier tasks unblock later ones) -3. **Check the recommended model** — use the right tool for the job -4. **Read the referenced files** before starting — understand what exists -5. **Run `npx next build`** before committing — must pass with zero errors -6. **Push to `main`** — Portainer auto-deploys via Gitea webhook - -### Model Legend - -| Tag | Model | Best For | -|---|---|---| -| `[OPUS]` | Claude Opus 4.6 | Complex multi-file features, business logic, architecture decisions | -| `[SONNET]` | Claude Sonnet 4.5 | Refactoring, UI work, moderate features, documentation | -| `[HAIKU]` | Claude Haiku 4.5 | Quick fixes, small edits, build debugging, simple tasks | +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 --- -## Phase 1 — Quality & Stability (do first) +## AI Model Recommendations -> Zero tests exist. No CI. Docs are stale. Fix the foundation before adding features. +| 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 | -### 1.1 `[SONNET]` Install Testing Framework - -**Complexity:** Low -**Files to create:** `vitest.config.ts`, `src/test-setup.ts` -**Files to modify:** `package.json` - -Install and configure: -```bash -npm install -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom -``` - -Create `vitest.config.ts` with: -- `environment: 'jsdom'` -- `setupFiles: ['./src/test-setup.ts']` -- Path aliases matching `tsconfig.json` (`@/` → `src/`) -- Coverage with `@vitest/coverage-v8` - -Add scripts to `package.json`: -```json -"test": "vitest run", -"test:watch": "vitest", -"test:coverage": "vitest run --coverage" -``` - -**Acceptance:** `npm test` runs without errors (0 tests found is OK at this point). +**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]`. --- -### 1.2 `[SONNET]` Unit Tests — Core Services +## Current Module Status vs. XLSX Spec -**Complexity:** Medium -**Depends on:** 1.1 +| # | 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/core/storage/adapters/__tests__/local-storage.test.ts` -- `src/core/feature-flags/__tests__/feature-flags.test.ts` -- `src/core/tagging/__tests__/tag-service.test.ts` -- `src/modules/registratura/services/__tests__/working-days.test.ts` -- `src/modules/registratura/services/__tests__/deadline-service.test.ts` -- `src/modules/registratura/services/__tests__/registry-service.test.ts` +- `src/modules/address-book/services/vcard-export.ts` -**Priority tests:** -1. `working-days.test.ts` — Critical: verify Orthodox Easter dates for 2024-2030, verify `addWorkingDays()` skips holidays/weekends, verify backward calculation for `prelungire-ac` -2. `deadline-service.test.ts` — Verify `createTrackedDeadline()` computes correct due dates, tacit approval detection, chain resolution -3. `local-storage.test.ts` — CRUD operations, namespace isolation, list filtering -4. `feature-flags.test.ts` — Default values, env overrides, flag evaluation -5. `registry-service.test.ts` — Registry number generation (`B-0001/2026`), overdue calculation +--- + +### 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. --- -### 1.3 `[SONNET]` Unit Tests — Module Services +### 3.03 `[STANDARD]` Data Export/Import for All Modules -**Complexity:** Medium -**Depends on:** 1.1 -**Files to create:** -- `src/modules/email-signature/services/__tests__/signature-service.test.ts` -- `src/modules/word-xml/services/__tests__/xml-service.test.ts` -- `src/modules/prompt-generator/services/__tests__/prompt-service.test.ts` +**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 -Test the pure business logic functions in each module's `services/` directory. - ---- - -### 1.4 `[HAIKU]` Update Stale Documentation - -**Complexity:** Low -**Files to modify:** -- `docs/architecture/SYSTEM-ARCHITECTURE.md` — Appendix B module catalog: change all 13 modules from "Planned" to "Implemented" with current feature summary -- `docs/DATA-MODEL.md` — Add `TrackedDeadline` and `DeadlineTypeDef` schemas (from `src/modules/registratura/types.ts`) -- `docs/REPO-STRUCTURE.md` — Add new registratura files (deadline services, components, hooks) - ---- - -### 1.5 `[HAIKU]` Wire External Tool URLs to Environment Variables - -**Complexity:** Low -**Files to modify:** `src/config/external-tools.ts` -**Reference:** `src/config/external-tools.ts` currently has hardcoded `http://10.10.10.166:PORT` URLs - -Change each tool URL to read from `process.env.NEXT_PUBLIC_*_URL` with fallback to current hardcoded values: -```typescript -url: process.env.NEXT_PUBLIC_GITEA_URL ?? 'http://10.10.10.166:3002' -``` - -The env vars are already defined in `.env.example` — just need to wire them up. - ---- - -### 1.6 `[SONNET]` Add Data Export/Import for All Modules - -**Complexity:** Medium **Files to create:** `src/shared/hooks/use-data-export.ts`, `src/shared/components/common/data-export-button.tsx` -**Files to modify:** Each module's main component (add export/import buttons) - -Currently there is no way to back up localStorage data. Create a shared utility that: -1. Exports all data for a module namespace as a JSON file download -2. Imports a JSON file and merges/replaces module data -3. Exports ALL module data as a single JSON backup - -This is critical before any storage migration — users need to export their data first. --- -## Phase 2 — Authentication & Multi-User (Authentik SSO) +### 3.04 `[LIGHT]` Update Stale Documentation -> Currently everyone is a stub admin. This phase adds real identity. - -### 2.1 `[OPUS]` Authentik OIDC Integration - -**Complexity:** High -**Files to modify:** -- `src/core/auth/auth-provider.tsx` — Replace stub user with real OIDC token resolution -- `src/core/auth/types.ts` — Add OIDC token types -**Files to create:** -- `src/core/auth/authentik-client.ts` — OIDC client configuration -- `src/app/api/auth/[...nextauth]/route.ts` — NextAuth.js route handler (or Auth.js v5) -**Dependencies to install:** `next-auth` (or `@auth/core`) - -**Setup required on server:** -1. Create an OAuth2/OIDC application in Authentik (http://10.10.10.166:9100) -2. Set redirect URI to `http://10.10.10.166:3000/api/auth/callback/authentik` -3. Note the Client ID and Client Secret -4. Set env vars: `AUTHENTIK_URL`, `AUTHENTIK_CLIENT_ID`, `AUTHENTIK_CLIENT_SECRET`, `NEXTAUTH_SECRET` - -**Behavior:** -- Unauthenticated users redirect to Authentik login -- On successful auth, resolve user profile (name, email, role, company) -- Store session in cookie (not localStorage) -- `useAuth()` hook returns real user instead of stub - -**Authentik is already running** at `http://10.10.10.166:9100`. You need: -- Admin credentials for Authentik (ask the admin) -- A generated `NEXTAUTH_SECRET` (run `openssl rand -base64 32`) +**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 --- -### 2.2 `[SONNET]` Module-Level Access Control +### 3.05 `[LIGHT]` Wire External Tool URLs to Env Vars -**Complexity:** Medium -**Depends on:** 2.1 -**Files to modify:** -- `src/core/auth/auth-provider.tsx` — Implement `canAccessModule()` with role-based rules -- `src/core/feature-flags/index.ts` — Combine feature flags with auth permissions - -**Behavior:** -- Admins can access all modules -- Regular users see only modules assigned to their role/company -- `FeatureGate` component checks both flag AND permission +**What:** `src/config/external-tools.ts` has hardcoded IPs. Wire to `process.env.NEXT_PUBLIC_*_URL` with fallback. --- -### 2.3 `[SONNET]` Data Visibility Enforcement +## PHASE 4 — AI Chat Integration -**Complexity:** Medium -**Depends on:** 2.1 -**Files to modify:** -- `src/core/storage/adapters/local-storage.ts` — Filter results by `visibility` and `createdBy` -- Each module's hook (e.g., `use-registry.ts`) — Pass current user context to storage queries +> Make Module 13 functional. -**Reference:** `docs/architecture/SECURITY-AND-ROLES.md` describes the 4 visibility levels: `all`, `company`, `admin`, `private`. +### 4.01 `[HEAVY]` AI Chat — Real API Integration -Currently stored on every entity but never enforced. +**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 ---- - -### 2.4 `[HAIKU]` Audit Logging Stub - -**Complexity:** Low -**Depends on:** 2.1 -**Files to create:** `src/core/audit/audit-service.ts` - -Create a simple audit service that logs actions (create, update, delete) with user ID and timestamp. Initially log to console; later pipe to storage/N8N. - ---- - -## Phase 3 — Storage Migration (localStorage → Backend) - -> Move from browser-only storage to a shared backend. All users see the same data. - -### 3.1 `[OPUS]` API Storage Adapter - -**Complexity:** High -**Files to create:** -- `src/core/storage/adapters/api-storage.ts` — `ApiStorageAdapter` implementing `StorageService` -- Backend API (separate project or Next.js API routes) -**Files to modify:** -- `src/core/storage/storage-provider.tsx` — Uncomment env-var-driven adapter selection - -**Reference:** Full spec in `docs/architecture/STORAGE-LAYER.md` lines 100-126. - -**Decision needed:** Build the API as: -- (a) Next.js API routes within ArchiTools (simpler, same repo) -- (b) Separate Express/Fastify service (decoupled, but more infra) -- (c) Direct PostgreSQL via Prisma from Next.js server components - -**Recommendation:** Option (c) with Prisma — simplest path, no separate service, works with the existing Next.js app. - -**Dependencies to install:** `prisma`, `@prisma/client` - ---- - -### 3.2 `[OPUS]` Database Schema & Migrations - -**Complexity:** High -**Depends on:** 3.1 -**Files to create:** -- `prisma/schema.prisma` — All entity models (RegistryEntry, Contact, Equipment, etc.) -- `prisma/migrations/` — Generated migration files - -**Reference:** `docs/DATA-MODEL.md` has all entity schemas. - -**Infrastructure:** PostgreSQL container on `10.10.10.166`. Add to `docker-compose.yml`: -```yaml -postgres: - image: postgres:16-alpine - environment: - POSTGRES_DB: architools - POSTGRES_USER: architools - POSTGRES_PASSWORD: - volumes: - - postgres-data:/var/lib/postgresql/data - networks: - - proxy-network -``` - ---- - -### 3.3 `[SONNET]` Data Migration Tool (localStorage → DB) - -**Complexity:** Medium -**Depends on:** 3.2 -**Files to create:** `src/app/api/migrate/route.ts` or a CLI script - -One-time migration: export all localStorage data as JSON, POST to the API, which inserts into PostgreSQL. Must handle: -- ID preservation (don't regenerate UUIDs) -- Timestamp preservation -- Attachment data (base64 → MinIO in Phase 3.4) - ---- - -### 3.4 `[OPUS]` MinIO Storage Adapter - -**Complexity:** Medium -**Depends on:** 3.1 -**Files to create:** `src/core/storage/adapters/minio-storage.ts` -**Dependencies to install:** `minio` (Node.js SDK) - -**Reference:** `docs/architecture/STORAGE-LAYER.md` lines 117-126. - -**MinIO is already running** at `http://10.10.10.166:9003`. You need: -- Access key and secret key (ask the admin or check Portainer env vars) -- Create a bucket named `architools` - -**Modules that will use MinIO for files:** -- Registratura — entry attachments (currently base64 in localStorage) -- Digital Signatures — signature/stamp images -- Word Templates — template file references - ---- - -## Phase 4 — AI Chat Integration - -> The AI Chat module has full UI but no real API calls. Enable it. - -### 4.1 `[OPUS]` AI Chat API Integration - -**Complexity:** High -**Files to modify:** -- `src/modules/ai-chat/components/ai-chat-module.tsx` — Replace demo response with real API call -- `src/modules/ai-chat/services/` — Create `ai-service.ts` with provider abstraction -**Files to create:** -- `src/modules/ai-chat/services/ai-service.ts` — Provider interface + implementations -- `src/modules/ai-chat/services/providers/anthropic.ts` -- `src/modules/ai-chat/services/providers/openai.ts` -- `src/modules/ai-chat/services/providers/ollama.ts` -- `src/app/api/ai/chat/route.ts` — Server-side proxy (API keys must not be exposed to browser) - -**Architecture:** -- Browser sends message to Next.js API route (`/api/ai/chat`) -- API route forwards to selected provider (Claude, GPT, Ollama) -- Response streamed back to browser via ReadableStream -- API keys stored in server-side env vars (never `NEXT_PUBLIC_`) - -**Env vars to add:** +**Env vars:** ``` ANTHROPIC_API_KEY=sk-ant-... OPENAI_API_KEY=sk-... -OLLAMA_BASE_URL=http://10.10.10.166:11434 # if running Ollama +OLLAMA_BASE_URL=http://10.10.10.166:11434 AI_DEFAULT_PROVIDER=anthropic -AI_DEFAULT_MODEL=claude-sonnet-4-5-20250929 +AI_DEFAULT_MODEL=claude-sonnet-4-6-20261001 ``` -**No API keys exist yet.** User will need to obtain them when ready. +**User action needed:** Provide API keys when ready. --- -### 4.2 `[SONNET]` AI Chat — System Prompts & Context +### 4.02 `[STANDARD]` AI Chat — Domain-Specific System Prompts -**Complexity:** Medium -**Depends on:** 4.1 -**Files to create:** `src/modules/ai-chat/services/system-prompts.ts` - -Create domain-specific system prompts for architecture office use: +**What:** Architecture office-focused conversation modes: - Romanian construction law assistant +- Architectural visualization prompt crafter - Technical specification writer - Urban planning regulation lookup - Document drafting assistant - -Allow users to select a "mode" that sets the system prompt. +- Normative compliance checker --- -### 4.3 `[HAIKU]` Enable AI Chat Feature Flag +### 4.03 `[LIGHT]` Enable AI Chat Feature Flag -**Complexity:** Trivial -**Depends on:** 4.1 -**Files to modify:** `src/config/flags.ts` — Set `module.ai-chat` to `enabled: true` - -Also enable in production `.env` on Portainer. +**What:** Set `module.ai-chat` enabled in `flags.ts` + production `.env`. --- -## Phase 5 — New Features & Modules +## PHASE 5 — Authentication (Authentik SSO) -> Expand the platform with new capabilities. +> Real users, real permissions. Requires server admin access. -### 5.1 `[OPUS]` Project Entity & Cross-Module Linking +### 5.01 `[HEAVY]` Authentik OIDC Integration -**Complexity:** High -**Files to create:** -- `src/modules/projects/` — Full module (types, config, components, hooks, services) -- `src/config/modules.ts` — Register the module -- `src/config/navigation.ts` — Add sidebar entry -- `src/app/(modules)/projects/page.tsx` — Route page +**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 -**Reference:** `docs/DATA-MODEL.md` lines 566-582 describe the `Project` interface. +**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` -A Project is the central entity that ties together: -- Registratura entries (documents for this project) -- Tags (project-scoped tags) -- Address Book contacts (client for this project) -- Word Templates (documents generated for this project) - -**This is the most impactful new module** — it connects all existing modules into a coherent workflow. - -**Legacy reference:** `legacy/manicprojects/current manic time Tags.txt` contains real project numbers and names to use as seed data. +**User action needed:** Authentik admin credentials. --- -### 5.2 `[SONNET]` Global Search +### 5.02 `[STANDARD]` Module-Level Access Control -**Complexity:** Medium -**Files to create:** -- `src/shared/components/common/global-search.tsx` -- `src/shared/hooks/use-global-search.ts` - -Search across all modules: registry entries, contacts, equipment, templates, passwords, tags. Each module registers a search provider with a common interface. - -Add to the header bar (Cmd+K keyboard shortcut). +**What:** Implement `canAccessModule()` with role-based rules. FeatureGate checks flag + permission. +**Depends on:** 5.01 --- -### 5.3 `[SONNET]` Notification System +### 5.03 `[STANDARD]` Data Visibility Enforcement -**Complexity:** Medium -**Files to create:** -- `src/core/notifications/notification-service.ts` -- `src/core/notifications/notification-provider.tsx` -- `src/shared/components/common/notification-bell.tsx` - -In-app notifications for: -- Deadline approaching (from Registratura termene legale) -- Deadline overdue -- Tacit approval triggered -- AC expiry warning (backward deadline) - -Show a bell icon in the header with unread count. Store notifications in localStorage (later in DB). +**What:** Filter storage results by `visibility` and `createdBy` fields (already stored on every entity, never enforced). +**Depends on:** 5.01 --- -### 5.4 `[SONNET]` Registratura — Print/PDF Export +### 5.04 `[LIGHT]` Audit Logging -**Complexity:** Medium -**Files to create:** -- `src/modules/registratura/components/registry-print-view.tsx` -- `src/modules/registratura/services/pdf-export.ts` - -Export the registry as a formatted PDF for printing. Options: -- Full registry for a date range -- Single entry detail sheet -- Deadline summary report -- Filter by company - -Use browser `print()` with a styled print layout, or integrate with Stirling PDF (http://10.10.10.166:8087) API. +**What:** Log create/update/delete actions with user ID + timestamp. Console initially, later storage/N8N. +**Depends on:** 5.01 --- -### 5.5 `[OPUS]` N8N Webhook Integration +## PHASE 6 — Storage Migration (localStorage → Database) -**Complexity:** Medium -**Files to create:** -- `src/core/webhooks/webhook-service.ts` -- `src/app/api/webhooks/n8n/route.ts` +> Multi-user shared data. Requires PostgreSQL + infrastructure changes. -Fire webhooks to N8N (http://10.10.10.166:5678) on events: -- New registry entry created -- Deadline approaching (daily check) -- Entry status changed (deschis → inchis) +### 6.01 `[HEAVY]` PostgreSQL + Prisma Setup -N8N can then trigger: email notifications, Slack messages, Google Calendar events, etc. +**What:** Add PostgreSQL container, create Prisma schema for all entities, run migrations. +**Infrastructure:** New `postgres` service in `docker-compose.yml`. --- -### 5.6 `[HAIKU]` Enable Remaining Module Feature Flags +### 6.02 `[HEAVY]` API Storage Adapter -**Complexity:** Trivial -**Files to modify:** `src/config/flags.ts` - -Currently disabled by default: `digital-signatures`, `password-vault`, `it-inventory`, `address-book`, `word-templates`, `mini-utilities`, `ai-chat`. - -Decide which modules should be enabled in production. Update both `flags.ts` defaults and the Portainer `.env`. +**What:** Create `ApiStorageAdapter` implementing `StorageService`. Use Next.js API routes + Prisma. +**Depends on:** 6.01 --- -### 5.7 `[SONNET]` Mobile Responsiveness Audit +### 6.03 `[STANDARD]` Data Migration Tool -**Complexity:** Medium -**Files to modify:** Various module components - -Test all 13 modules on mobile viewports (375px, 768px). Fix: -- Tables that overflow -- Forms that are too wide -- Sidebar behavior on mobile -- Touch targets too small +**What:** One-time export from localStorage → import to PostgreSQL. Preserve IDs and timestamps. +**Depends on:** 6.02 --- -## Phase 6 — External Access & Security Hardening +### 6.04 `[HEAVY]` MinIO File Storage -> Open the app beyond the internal network. - -### 6.1 `[OPUS]` Guest/External Access Role - -**Complexity:** High -**Depends on:** 2.1 (Authentik) -**Reference:** `docs/architecture/SECURITY-AND-ROLES.md` — Phase 4 - -Add a `guest` role with: -- Read-only access to specific modules -- No access to Password Vault, IT Inventory -- Time-limited share links for specific entries -- No edit/delete capabilities +**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. --- -### 6.2 `[SONNET]` CrowdSec Integration +## PHASE 7 — Advanced Features -**Complexity:** Medium -**Reference:** `docs/architecture/SECURITY-AND-ROLES.md` — CrowdSec listed as planned +> Cross-cutting features that enhance the entire platform. -CrowdSec is already running at `http://10.10.10.166:8088`. Configure: -- Nginx Proxy Manager log parsing -- Automatic IP ban for brute force / scanning -- ArchiTools-specific scenarios (rate limiting API routes) +### 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. --- -### 6.3 `[HAIKU]` SSL/TLS via Let's Encrypt +### 7.02 `[STANDARD]` Global Search (Cmd+K) -**Complexity:** Low - -When a public domain is configured (e.g., `tools.beletage.ro`): -1. Point DNS to server IP -2. Configure Let's Encrypt in Nginx Proxy Manager -3. Update `NEXT_PUBLIC_APP_URL` to `https://tools.beletage.ro` -4. Force HTTPS redirect +**What:** Search across all modules. Each module registers a search provider. Header bar integration. --- -## Phase 7 — CI/CD Pipeline +### 7.03 `[STANDARD]` Notification System -> Automate quality checks on every push. - -### 7.1 `[SONNET]` Gitea Actions CI Pipeline - -**Complexity:** Medium -**Depends on:** 1.1, 1.2 (tests exist) -**Files to create:** `.gitea/workflows/ci.yml` - -Gitea supports GitHub Actions-compatible workflows. Create a pipeline that runs on push to `main`: - -```yaml -steps: - - npm ci - - npm run lint - - npx tsc --noEmit # type check - - npm test # vitest - - npx next build # build check -``` - -**Note:** Check if Gitea Actions runner is installed on the server. If not, install one: -```bash -docker run -d --name gitea-runner \ - -v /var/run/docker.sock:/var/run/docker.sock \ - gitea/act_runner:latest -``` +**What:** Bell icon in header. Deadline alerts, overdue warnings, tacit approval triggers. --- -### 7.2 `[SONNET]` E2E Tests with Playwright +### 7.04 `[STANDARD]` Registratura — Print/PDF Export -**Complexity:** High -**Depends on:** 1.1 -**Files to create:** -- `playwright.config.ts` -- `e2e/registratura.spec.ts` -- `e2e/email-signature.spec.ts` -- `e2e/navigation.spec.ts` - -**Reference:** `docs/guides/TESTING-STRATEGY.md` describes 6 critical E2E flows. - -Install: `npm install -D @playwright/test` +**What:** Export registry as formatted PDF. Options: full registry, single entry, deadline summary. --- -## Appendix: Infrastructure Credentials Needed +### 7.05 `[STANDARD]` Word Templates — Clause Library + Document Generator -| Service | What's Needed | Who Has It | +**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 | |---|---|---| -| **Authentik** | Admin login to create OAuth app | Server admin | -| **MinIO** | Access key + secret key | Server admin / Portainer env | -| **Anthropic API** | API key (`sk-ant-...`) | Purchase at console.anthropic.com | -| **OpenAI API** | API key (`sk-...`) | Purchase at platform.openai.com | -| **Gitea Actions** | Runner registration token | Gitea admin → Site Admin → Runners | -| **PostgreSQL** | New container + credentials | Create via docker-compose.yml | +| **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) | --- -## Appendix: Quick Task Picker +## Quick Picker -**I have 15 minutes:** -- 1.5 (wire external tool URLs) `[HAIKU]` -- 1.4 (update stale docs) `[HAIKU]` -- 5.6 (enable feature flags) `[HAIKU]` +**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 -**I have 1 hour:** -- 1.1 + 1.2 (install tests + write core tests) `[SONNET]` -- 1.6 (data export/import) `[SONNET]` -- 5.2 (global search) `[SONNET]` +**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 -**I have a full session:** -- 2.1 (Authentik SSO) `[OPUS]` -- 3.1 + 3.2 (API + database) `[OPUS]` -- 4.1 (AI Chat API) `[OPUS]` -- 5.1 (Project entity) `[OPUS]` +**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