gitadmin/ArchiTools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d6a5852e5462b7e228553462ac67d7939cc72cf9
ArchiTools/ROADMAP.md
Marius Tarau d6a5852e54 docs: add ROADMAP.md with detailed future task plan 
7 phases, 23 tasks with model recommendations, complexity ratings,
file references, infrastructure requirements, and dependency chains.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-18 11:40:14 +02:00

19 KiB
Raw Blame History

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:

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:

"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:

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:

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:

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:

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]
Reference in New Issue View Git Blame Copy Permalink