Security Notice

This document has been auto-published from the internal knowledge base. All passwords, API keys, tokens, and IP addresses have been redacted for security.

CHAROS Apps Specialist

HandyManny — Tracking Portal (ACTIVE, MULTI-TENANT)

Basics

• Live: charos.handymanny.cloud (CHAROS) | u1st.handymanny.cloud (U1ST)
• Source: ~/projects/handymanny/
• Deploy: ./deploy.sh charos | ./deploy.sh u1st | ./deploy-all.sh
• Stack: Next.js 16 + React 19 + TypeScript + Tailwind v4 + Prisma 6 + PostgreSQL 16 + NextAuth v5
• Admin: user@example.com / [PASSWORD]
• GitHub: github.com/chavez684/handymanny (private)

Multi-Tenant Architecture

• Single codebase, branding via NEXT_PUBLIC_BRAND_* env vars + CSS custom properties (--brand, etc.)
• Brand config: src/lib/brand.ts — reads env vars, CHAROS defaults
• Docker: Separate containers per tenant (independent PostgreSQL, same Traefik)
• NEXT_PUBLIC_ are build-time* — changing requires Docker rebuild (not just restart)

Tenant	URL	Port	Branding
CHAROS	charos.handymanny.cloud	3002	Red #d93324
U1ST	u1st.handymanny.cloud	3004	Blue #1e40af

49 Features Built

• Core: Auth (5 roles), Dashboard, Shipment CRUD + Edit, Customer List, Public Tracking, Inbox, Webhooks
• Multi-tenant (2026-02-22): White-label branding, deploy scripts, CSS vars
• CHAROS AI (2026-02-22): Floating chat widget, Claude Haiku 4.5, 5 shipment tools, image upload, rate-limited
• Maps (2026-02-22/23): Unified Shipments Map (truck+ocean), Leaflet/OSM, 3-tier geocoding (hardcoded→Nominatim→AI), voyage route polylines, "Rutas" toggle, sin ubicacion badge+panel
• Archive system (2026-02-23): archivedAt field, ArchiveButton, Finalizados tab
• Inline dropdowns (2026-02-23): StatusDropdown (8 statuses, archive prompt), PositionDropdown (~90 known locations)
• Analytics (2026-02-23): /analytics (admin-only, recharts), carrier/destination/company/transit charts
• Incidents (2026-02-23): ShipmentIncident model, CRUD API, IncidentsPanel (admin/dispatcher only)
• Pre-Shipment (2026-02-23): pre_asignado status, bookingNumber + clientReference, Pre-Embarque tab
• Bulk Notifications (2026-02-23): 5-step wizard, email/whatsapp/both, NotificationLog
• Other: Customer filter, company slugs, password reset, customer team management, platform invitations, carrier branding, clickable KPIs, auto-track cron (every 4h)

DB Schema (12 Models)

User, Company, Contact, Shipment (archivedAt, bookingNumber, clientReference, lat/lng, position fields), ShipmentContainer, ShipmentIncident, CompanyShipment, NotificationPreference, NotificationLog (recipientEmail/Name), Message, PlatformInvitation, PasswordResetToken

Key Files

• src/lib/brand.ts — Brand config
• prisma/schema.prisma — 12 models + enums
• src/middleware.ts — Route protection, role-based access
• src/lib/known-locations.ts — ~90 hardcoded locations (ports, cities, borders)
• src/lib/geocoding.ts — 3-tier pipeline (hardcoded→Nominatim→AI)
• src/lib/chat-tools.ts — CHAROS AI tool definitions
• src/lib/email-client.ts — Resend API (noreply@handymanny.cloud)
• fix-pw.js — Password fix (runs in deploy.sh)

Public APIs

• GET /api/dashboard/stats — public, returns shipment/incident counts (used by CrowBot)
• POST /api/track-public — public CORS *, calls Ocean Tracker, geocodes, returns enriched JSON
• POST /api/chat/public — no auth, IP rate limit (10/min), Manny persona

Known Issues

• .env quoting: Values with spaces MUST be quoted
• fix-pw.js runs on every deploy (scoped to admin roles)
• 3 carriers blocked (OOCL, Wan Hai, ZIM)
• Seed trucks expired (status_category=expired)

n8n Workflows

Workflow	ID	Status
Auto-Track (every 4h)	XEYwLqrwEJwCz39g	ACTIVE
Shipment Notice Emailer	dH1nNvwPxR3eyGU8	ACTIVE (MSC merge bug FIXED)
Geocode AI	J76GltqEdd731XGY	ACTIVE

HandyManny Mission Control (In-App)

• URL: charos.handymanny.cloud/missioncontrol (no auth)
• Source: ~/projects/handymanny/public/missioncontrol/index.html
• 14 sections, sidebar with app status polling

---

Expediente — Document Management (Regla 1.4.14)

Basics

• Live: expediente.handymanny.cloud | Source: ~/projects/expediente/
• Deploy: bash ~/projects/expediente/deploy.sh
• Stack: Next.js 16 + Prisma 6 + PostgreSQL 16 + NextAuth v5 + Tailwind v4
• Port: 3005 | Admin: user@example.com
• Brand: CHAROS (#d93324) — white-label via 10 NEXT_PUBLIC_BRAND_* env vars
• 62 files built. QA 11/11 pass (2026-02-22)

DB Schema (9 models, 6 enums)

User, Client, DocumentType (+aiExtractable), ClientTypeDocument, Document (+extractedData), DocumentReview, AuditLog, NotificationLog, Contract

Features vs Legacy

Feature	Added
White-label (10 env vars)	New
AI Extraction (6 doc schemas, Claude Haiku Vision)	New
Monthly Renewal (4-tier reminders)	New
Contract Generation (Carta Encomienda, Formato A)	New
Notification History (paginated, filtered)	New

n8n Workflows (4 ACTIVE)

Workflow	ID	Webhook
Notifications	uMvWVvFbRcfB2qyV	/expediente-notify
AI Extract	0DN5KduorqBsJk4B	/expediente-extract
Monthly Reset	fJwklRmPNVdxjARl	/expediente-monthly-reset
Contract Generate	owJ7egjjRphZIqgY	/expediente-contract

TODO

• [ ] Google Drive service account
• [ ] End-to-end QA testing
• [ ] Test white-label with different brand configs

---

Consultin Shipments Gruas — Operations Center

• Live: consultin.handymanny.cloud | Source: ~/projects/consultin-gruas/
• Deploy: bash ~/projects/consultin-gruas/deploy.sh
• Stack: Static HTML + CSS + JS (nginx:alpine) | localStorage persistence
• Features: KPI cards, import/export shipment table, milestone timelines (7 steps), document tracker (6 types), activity feed, SVG world map with animated routes, add/delete shipments
• Carriers: MSC (imports) | ONE (exports) | Mexican ports: Manzanillo, Lazaro Cardenas, Veracruz, Altamira
• VPS: srv1139900, container consultin-gruas

---

Handy Manny Landing Page

• Live: handymanny.cloud | Source: ~/projects/handymanny-site/
• Deploy: cd ~/projects/handymanny-site && bash deploy.sh
• Stack: nginx:alpine, static HTML/CSS/JS
• Design: Minimal personal landing — dark bg, particle canvas, HM hex logo, bio, contact pills
• Chat widget: Calls charos.handymanny.cloud/api/chat/public (Manny AI, Claude Haiku)
• Redirects: Old paths (/track/*, /api/*, etc.) → charos.handymanny.cloud

---

FFTracking — Freight Forwarding Portal (MVP BUILT 2026-02-24)

Basics

• Planned URL: fftracking.handymanny.cloud | Source: ~/projects/fftracking/
• Deploy: bash ~/projects/fftracking/deploy.sh
• Stack: Next.js 16 + React 19 + TypeScript + Tailwind v4 + Prisma 6 + PostgreSQL 16 + NextAuth v5
• Port: 3004 | Admin: admin@fftracking.com / [PASSWORD]
• Files: 32 source files, 45 total committed, build passing
• Multi-tenant: Same NEXT_PUBLIC_BRAND_* pattern as HandyManny

DB Schema (8 Models, 8 Enums)

User, Company, Shipment, CompanyShipment, Container, Booking, Document, Invoice Enums: UserRole (5), ShipmentMode (3), ShipmentStatus (7), ContainerSize (6), BookingStatus (4), DocumentType (11), InvoiceStatus (4), CompanyShipmentRole (3)

Pages (15 Routes)

• Auth: Login (split layout, OEC-inspired)
• Dashboard: Welcome banner, 4 KPI cards, shipment funnel (recharts bar), billing donut (pie), recent docs
• Shipments: Card list (OEC pattern) + filters + pagination, detail with 4 tabs (General/Containers/Documents/Billing), new form
• Documents: Table layout, doc type filter, search
• Billing: Table layout, status filter, search
• Bookings: Phase 2 placeholder
• Reports: Phase 2 placeholder
• API: 6 routes (shipments CRUD, documents, invoices, dashboard stats)

Design Pattern

• White sidebar with red active state + left border accent (OEC-inspired)
• Topbar with global search + notification bell + user avatar
• Card layout for shipments, table layout for documents/billing

Docker Config

Setting	Value
Container	fftracking
DB container	fftracking-postgres
Port	3004
VPS path	/docker/fftracking
Traefik router	fftracking
Domain	fftracking.handymanny.cloud

Status: MVP built, NOT YET DEPLOYED

• Next: deploy.sh to VPS, configure .env, verify SSL

---

Planned (Not Started)

• Comercializadora: Import operations tracking through 19 Mexican customs stages
• Certificado de Molino: Mill test certificates (EN 10204)

Staffing Needs

Role	Priority	Status
Full-Stack Dev (Next.js/Prisma)	ASAP	Open
Scraping/Anti-Bot Specialist	ASAP	Hamid — STARTING
Logistics Domain Expert	When dev starts	Open
Flutter/Mobile Dev	When VIA design done	Open