ArchiTools/ROADMAP.md

# ArchiTools — Roadmap & Future Tasks

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

---

## How to Use This File

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 |

---

## Phase 1 — Quality & Stability (do first)

> Zero tests exist. No CI. Docs are stale. Fix the foundation before adding features.

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

---

### 1.2 `[SONNET]` Unit Tests — Core Services

**Complexity:** Medium
**Depends on:** 1.1
**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`

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

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

---

### 1.3 `[SONNET]` Unit Tests — Module Services

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

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)

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

---

### 2.2 `[SONNET]` Module-Level Access Control

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

---

### 2.3 `[SONNET]` Data Visibility Enforcement

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

**Reference:** `docs/architecture/SECURITY-AND-ROLES.md` describes the 4 visibility levels: `all`, `company`, `admin`, `private`.

Currently stored on every entity but never enforced.

---

### 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: <generate-secure-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:**
```
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OLLAMA_BASE_URL=http://10.10.10.166:11434  # if running Ollama
AI_DEFAULT_PROVIDER=anthropic
AI_DEFAULT_MODEL=claude-sonnet-4-5-20250929
```

**No API keys exist yet.** User will need to obtain them when ready.

---

### 4.2 `[SONNET]` AI Chat — System Prompts & Context

**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:
- Romanian construction law assistant
- Technical specification writer
- Urban planning regulation lookup
- Document drafting assistant

Allow users to select a "mode" that sets the system prompt.

---

### 4.3 `[HAIKU]` 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.

---

## Phase 5 — New Features & Modules

> Expand the platform with new capabilities.

### 5.1 `[OPUS]` Project Entity & Cross-Module Linking

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

**Reference:** `docs/DATA-MODEL.md` lines 566-582 describe the `Project` interface.

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.

---

### 5.2 `[SONNET]` Global Search

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

---

### 5.3 `[SONNET]` Notification System

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

---

### 5.4 `[SONNET]` Registratura — Print/PDF Export

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

---

### 5.5 `[OPUS]` N8N Webhook Integration

**Complexity:** Medium
**Files to create:**
- `src/core/webhooks/webhook-service.ts`
- `src/app/api/webhooks/n8n/route.ts`

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)

N8N can then trigger: email notifications, Slack messages, Google Calendar events, etc.

---

### 5.6 `[HAIKU]` Enable Remaining Module Feature Flags

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

---

### 5.7 `[SONNET]` Mobile Responsiveness Audit

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

---

## Phase 6 — External Access & Security Hardening

> 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

---

### 6.2 `[SONNET]` CrowdSec Integration

**Complexity:** Medium
**Reference:** `docs/architecture/SECURITY-AND-ROLES.md` — CrowdSec listed as planned

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)

---

### 6.3 `[HAIKU]` SSL/TLS via Let's Encrypt

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

---

## Phase 7 — CI/CD Pipeline

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

---

### 7.2 `[SONNET]` E2E Tests with Playwright

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

---

## Appendix: Infrastructure Credentials Needed

| Service | What's Needed | Who Has It |
|---|---|---|
| **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 |

---

## Appendix: Quick Task Picker

**I have 15 minutes:**
- 1.5 (wire external tool URLs) `[HAIKU]`
- 1.4 (update stale docs) `[HAIKU]`
- 5.6 (enable feature flags) `[HAIKU]`

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

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