diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..0375297 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,585 @@ +# 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: + 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]`