umpordez 0.0.2 → 1.0.0

package/template/code.md

@@ -0,0 +1,211 @@
+# Code Standards
+
+This document defines the coding standards for the project. All code
+must follow these rules. Read `architecture.md` for architecture
+patterns and how-tos.
+
+---
+
+## 1. Formatting
+
+- **4-space indentation**, semicolons, LF line endings
+- **No trailing commas** — not in arrays `[foo]`, objects `{foo}`,
+  function calls `(foo)`, or parameters. Never `(foo,)` or `[foo,]`
+- **Max 80 columns** per line — especially for `if` conditions,
+  function signatures, and long strings. Break across lines:
+
+```typescript
+// bad
+if (userRole !== 'owner' && userRole !== 'admin' && userRole !== 'manager') {
+
+// good
+if (
+    userRole !== 'owner'
+    && userRole !== 'admin'
+    && userRole !== 'manager'
+) {
+```
+
+## 2. Braces
+
+**Always use braces** for `if`, `else`, `for`, `while`.
+No single-line bodies without braces.
+
+```typescript
+// bad
+if (foo) bar();
+if (foo)
+    bar();
+for (const x of arr) doSomething(x);
+
+// good
+if (foo) {
+    bar();
+}
+
+for (const x of arr) {
+    doSomething(x);
+}
+```
+
+## 3. Error Handling
+
+**Never silently ignore errors.** Every `catch` block must at
+minimum log the error with `logger.error()`:
+
+```typescript
+// bad
+try {
+    await deleteFromS3(key);
+} catch {
+    // ignore
+}
+
+// bad
+try {
+    await deleteFromS3(key);
+} catch (ex) { }
+
+// good
+try {
+    await deleteFromS3(key);
+} catch (err) {
+    logger.error('{context} failed to delete file', err);
+}
+```
+
+In route handlers, let errors propagate to `buildHandler()` — it
+catches and formats them automatically. Only use try/catch in routes
+when you need to handle a specific error differently.
+
+## 4. TypeScript
+
+- **TypeScript strict** in all packages
+- Use explicit types for function parameters and return types on
+  exported functions
+- Prefer `interface` over `type` for object shapes
+- Use `unknown` over `any` when the type is truly unknown
+- Use Zod schemas for runtime validation of external input
+  (request bodies, query params)
+
+## 5. Language
+
+- **Code in English** — variable names, function names, comments,
+  logs, error messages in code
+- **UI text in Portuguese** — user-facing strings, labels, toast
+  messages, validation messages shown to users
+- Error messages thrown by models should be in Portuguese (they're
+  sent to the frontend as-is)
+
+## 6. Naming
+
+| Type        | Convention    | Example                       |
+|-------------|--------------|-------------------------------|
+| Components  | PascalCase   | `NavUser.tsx`                 |
+| Hooks       | kebab-case   | `use-user.tsx`                |
+| Query hooks | kebab-case   | `use-accounts.ts`             |
+| Utils/Lib   | kebab-case   | `fetch-api.ts`                |
+| Routes      | kebab-case   | `demand-user.ts`              |
+| Models      | kebab-case   | `account.ts`                  |
+| Migrations  | timestamp    | `20260208000000_description.ts`|
+| DB columns  | snake_case   | `utc_created_on`              |
+| TS vars     | camelCase    | `accountRole`                 |
+
+## 7. Path Aliases
+
+- Server: `#core/*`, `#shared/*`, `#api/*`
+- Admin UI: `@/*` (maps to `src/`)
+
+Always use path aliases — never relative paths with `../../`.
+
+## 8. Database
+
+- **Raw SQL** in migrations (use `knex.schema.raw()`)
+- Every table must have: `id` (UUID), `utc_created_on`, `utc_updated_on`
+- Multi-tenant tables must have `account_id` with a foreign key
+- Use `generate_series()` for date-based aggregations
+- Filename format: `YYYYMMDDHHMMSS_description.ts`
+- Never store sensitive data unencrypted (passwords use bcrypt)
+
+## 9. Models
+
+- Extend `BaseModel`, access DB via `this.knex`
+- Access other models via `this.context.otherModel`
+- Always filter by `account_id` in multi-tenant queries
+- Use `PaginatedResult<T>`: `{ rows, total, page, limit, totalPages }`
+- Use `whereILike` for case-insensitive search
+- Parse JSON fields when reading, `JSON.stringify()` when writing
+- Throw `AppError` subclasses: `ValidationError` (400),
+  `UnauthorizedError` (401), `ForbiddenError` (403),
+  `NotFoundError` (404), `ConflictError` (409)
+
+## 10. Routes
+
+- Use `buildHandler()` wrapper for all async handlers
+- Export `makeEndpoint(app)` or `makeRoutes(app)`
+- Use Zod schemas for all request body validation
+- Middleware chain order:
+  `trySetUserByToken` → `demandUser` → `[demandAdmin|demandAccountAccess]`
+- Never do raw DB queries in routes — use models
+
+## 11. Frontend
+
+- Use `fetchApi()` for all API calls (handles cookies, errors, FormData)
+- Use React Query (`useQuery` / `useMutation`) for all server state
+- Use `keepPreviousData` on paginated/searchable queries
+- Add query keys to `lib/query-keys.ts`
+- Invalidate related queries in mutation `onSuccess`
+- Use `useConfirm()` instead of `window.confirm()`
+- Use `toast` from sonner for feedback messages
+
+## 12. File Uploads (S3)
+
+- Store only the S3 **key** in the database (`avatar_key`,
+  `document_key`), never the full URL
+- Serve files via **signed URLs** with short expiry (1 hour)
+- Never expose raw S3 URLs to the frontend — always resolve to
+  signed URLs on the backend before sending
+- Use `createS3Upload()` with explicit `allowedMimeTypes` and
+  `maxFileSize` — never accept all file types
+- Delete old files from S3 when replacing (e.g. avatar update)
+
+## 13. Charts
+
+Use pure CSS/Tailwind bars with Radix Tooltip — no recharts library
+needed (even though it's installed). Pattern:
+
+```tsx
+<TooltipProvider delayDuration={0}>
+    <div className="flex items-end gap-1 h-32">
+        {data.map((point) => (
+            <Tooltip key={point.id}>
+                <TooltipTrigger asChild>
+                    <div
+                        className="flex-1 rounded-sm bg-primary
+                            cursor-pointer transition-opacity
+                            hover:opacity-80"
+                        style={{ height: `${height}%` }}
+                    />
+                </TooltipTrigger>
+                <TooltipContent>
+                    <p>{point.label}</p>
+                    <p className="text-lg font-bold">{point.value}</p>
+                </TooltipContent>
+            </Tooltip>
+        ))}
+    </div>
+</TooltipProvider>
+```
+
+Calculate `maxValue` from data, derive bar heights as percentages
+with a minimum of 4% so empty bars are still visible.
+
+## 14. Security
+
+- Auth via httpOnly cookies only — no tokens in localStorage
+- All S3 files served through signed URLs (never public-read)
+- Validate all input with Zod before processing
+- Use parameterized queries (Knex handles this) — never
+  string-concatenate SQL
+- Admin users bypass `user_in_accounts` but still go through
+  `demand-account-access` middleware which sets `req.accountRole`

package/template/dev.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+
+echo "Starting All Services"
+echo "====================="
+echo ""
+echo "Starting services:"
+echo "  - Admin API (port {{API_PORT}})"
+echo "  - Site API  (port {{SITE_API_PORT}})"
+echo "  - Admin Panel (port {{ADMIN_UI_PORT}})"
+echo "  - Site (port {{SITE_PORT}})"
+echo ""
+echo "Press Ctrl+C to stop all services"
+echo ""
+
+trap 'kill $(jobs -p) 2>/dev/null' EXIT
+
+if [ ! -f server/.env ]; then
+    echo "Warning: server/.env not found"
+    echo "Run ./install.sh first"
+    exit 1
+fi
+
+echo "Starting Admin API..."
+(cd server && npm run dev) &
+
+echo "Starting Site API..."
+(cd server && npm run dev:site-api) &
+
+echo "Starting Admin Panel..."
+(cd ui/admin && npm run dev) &
+
+echo "Starting Site..."
+(cd ui/site && npm run dev) &
+
+echo ""
+echo "All services started!"
+echo ""
+echo "URLs:"
+echo "  - Site:          http://localhost:{{SITE_PORT}}"
+echo "  - Admin Panel:   http://localhost:{{ADMIN_UI_PORT}}"
+echo "  - Admin API:     http://localhost:{{API_PORT}}"
+echo "  - Site API:      http://localhost:{{SITE_API_PORT}}"
+echo ""
+
+wait

package/template/install.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+
+echo "Installing Dependencies"
+echo "======================="
+echo ""
+
+echo "Installing server dependencies..."
+(cd server && npm install)
+echo "Server dependencies installed"
+echo ""
+
+echo "Installing admin UI dependencies..."
+(cd ui/admin && npm install)
+echo "Admin UI dependencies installed"
+echo ""
+
+echo "Installing site UI dependencies..."
+(cd ui/site && npm install)
+echo "Site UI dependencies installed"
+echo ""
+
+echo "Setting up environment files..."
+echo ""
+
+if [ ! -f server/.env ]; then
+    cp server/.env.sample server/.env
+    echo "Created server/.env"
+else
+    echo "server/.env already exists"
+fi
+
+if [ ! -f ui/site/.env ]; then
+    cp ui/site/.env.sample ui/site/.env
+    echo "Created ui/site/.env"
+else
+    echo "ui/site/.env already exists"
+fi
+
+echo ""
+echo "======================="
+echo "Installation Complete!"
+echo ""
+echo "Next steps:"
+echo "1. Edit server/.env with your database credentials"
+echo "2. ./seed.sh       (create db + migrate + seed admin)"
+echo "3. ./dev.sh        (start all services)"
+echo ""

package/template/misc/nginx.conf

@@ -0,0 +1,151 @@
+# {{PROJECT_NAME}} — Nginx Configuration
+#
+# Setup:
+#   1. Copy this file to /etc/nginx/sites-available/{{PROJECT_SLUG}}
+#   2. ln -s /etc/nginx/sites-available/{{PROJECT_SLUG}} /etc/nginx/sites-enabled/
+#   3. Replace {{DOMAIN}} with your actual domain
+#   4. Run: sudo certbot --nginx -d {{DOMAIN}} -d app.{{DOMAIN}} -d api.{{DOMAIN}}
+#   5. sudo nginx -t && sudo systemctl reload nginx
+
+# ─── Upstreams ───────────────────────────────────────────────────────────────
+
+upstream api {
+    ip_hash;
+    server 127.0.0.1:{{API_PORT}};
+}
+
+upstream site_api {
+    ip_hash;
+    server 127.0.0.1:{{SITE_API_PORT}};
+}
+
+upstream site {
+    ip_hash;
+    server 127.0.0.1:{{SITE_PORT}};
+}
+
+# ─── Admin API (api.{{DOMAIN}}) ──────────────────────────────────────────────
+
+server {
+    listen 443 ssl;
+    server_name api.{{DOMAIN}};
+
+    ssl_certificate /etc/letsencrypt/live/{{DOMAIN}}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/{{DOMAIN}}/privkey.pem;
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+
+    client_max_body_size 50M;
+
+    location / {
+        proxy_pass http://api;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+    }
+}
+
+# ─── Site API (api-site.{{DOMAIN}}) ──────────────────────────────────────────
+
+server {
+    listen 443 ssl;
+    server_name api-site.{{DOMAIN}};
+
+    ssl_certificate /etc/letsencrypt/live/{{DOMAIN}}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/{{DOMAIN}}/privkey.pem;
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+
+    client_max_body_size 50M;
+
+    location / {
+        proxy_pass http://site_api;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+
+# ─── Admin Panel (app.{{DOMAIN}}) ────────────────────────────────────────────
+# React SPA — static files served by nginx directly
+
+server {
+    listen 443 ssl;
+    server_name app.{{DOMAIN}};
+
+    ssl_certificate /etc/letsencrypt/live/{{DOMAIN}}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/{{DOMAIN}}/privkey.pem;
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+
+    root /apps/{{PROJECT_SLUG}}/builds/ui/admin/dist;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Cache static assets
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+}
+
+# ─── Public Site ({{DOMAIN}}) ────────────────────────────────────────────────
+
+server {
+    listen 443 ssl;
+    server_name {{DOMAIN}};
+
+    ssl_certificate /etc/letsencrypt/live/{{DOMAIN}}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/{{DOMAIN}}/privkey.pem;
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+
+    location / {
+        proxy_pass http://site;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+
+# ─── WWW Redirect ────────────────────────────────────────────────────────────
+
+server {
+    listen 443 ssl;
+    server_name www.{{DOMAIN}};
+
+    ssl_certificate /etc/letsencrypt/live/{{DOMAIN}}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/{{DOMAIN}}/privkey.pem;
+
+    return 301 https://{{DOMAIN}}$request_uri;
+}
+
+# ─── HTTP → HTTPS Redirect ──────────────────────────────────────────────────
+
+server {
+    listen 80;
+    server_name {{DOMAIN}} www.{{DOMAIN}} app.{{DOMAIN}} api.{{DOMAIN}} api-site.{{DOMAIN}};
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/html;
+    }
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}

package/template/misc/systemd/{{PROJECT_SLUG}}-api.service

@@ -0,0 +1,31 @@
+# {{PROJECT_NAME}} — Admin API Service
+#
+# Setup:
+#   1. Copy to /etc/systemd/system/{{PROJECT_SLUG}}-api.service
+#   2. sudo systemctl daemon-reload
+#   3. sudo systemctl enable {{PROJECT_SLUG}}-api
+#   4. sudo systemctl start {{PROJECT_SLUG}}-api
+#
+# Logs:
+#   journalctl -u {{PROJECT_SLUG}}-api -f
+#   tail -f /apps/{{PROJECT_SLUG}}/log/api.log
+
+[Unit]
+Description={{PROJECT_NAME}} Admin API
+After=network.target postgresql.service
+Wants=postgresql.service
+
+[Service]
+Type=simple
+User=ubuntu
+Group=ubuntu
+WorkingDirectory=/apps/{{PROJECT_SLUG}}/builds/server
+ExecStart=/usr/bin/node apps/api/app.js
+Restart=always
+RestartSec=5
+StandardOutput=append:/apps/{{PROJECT_SLUG}}/log/api.log
+StandardError=append:/apps/{{PROJECT_SLUG}}/log/api.log
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target

package/template/misc/systemd/{{PROJECT_SLUG}}-site-api.service

@@ -0,0 +1,31 @@
+# {{PROJECT_NAME}} — Site API Service
+#
+# Setup:
+#   1. Copy to /etc/systemd/system/{{PROJECT_SLUG}}-site-api.service
+#   2. sudo systemctl daemon-reload
+#   3. sudo systemctl enable {{PROJECT_SLUG}}-site-api
+#   4. sudo systemctl start {{PROJECT_SLUG}}-site-api
+#
+# Logs:
+#   journalctl -u {{PROJECT_SLUG}}-site-api -f
+#   tail -f /apps/{{PROJECT_SLUG}}/log/site-api.log
+
+[Unit]
+Description={{PROJECT_NAME}} Site API
+After=network.target postgresql.service
+Wants=postgresql.service
+
+[Service]
+Type=simple
+User=ubuntu
+Group=ubuntu
+WorkingDirectory=/apps/{{PROJECT_SLUG}}/builds/server
+ExecStart=/usr/bin/node apps/site-api/app.js
+Restart=always
+RestartSec=5
+StandardOutput=append:/apps/{{PROJECT_SLUG}}/log/site-api.log
+StandardError=append:/apps/{{PROJECT_SLUG}}/log/site-api.log
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target

package/template/misc/systemd/{{PROJECT_SLUG}}-site.service

@@ -0,0 +1,30 @@
+# {{PROJECT_NAME}} — Public Site Service
+#
+# Setup:
+#   1. Copy to /etc/systemd/system/{{PROJECT_SLUG}}-site.service
+#   2. sudo systemctl daemon-reload
+#   3. sudo systemctl enable {{PROJECT_SLUG}}-site
+#   4. sudo systemctl start {{PROJECT_SLUG}}-site
+#
+# Logs:
+#   journalctl -u {{PROJECT_SLUG}}-site -f
+#   tail -f /apps/{{PROJECT_SLUG}}/log/site.log
+
+[Unit]
+Description={{PROJECT_NAME}} Public Site
+After=network.target
+
+[Service]
+Type=simple
+User=ubuntu
+Group=ubuntu
+WorkingDirectory=/apps/{{PROJECT_SLUG}}/builds/ui/site
+ExecStart=/usr/bin/node app.js
+Restart=always
+RestartSec=5
+StandardOutput=append:/apps/{{PROJECT_SLUG}}/log/site.log
+StandardError=append:/apps/{{PROJECT_SLUG}}/log/site.log
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target

package/template/seed.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+echo "Database Setup"
+echo "=============="
+echo ""
+
+DB_NAME="{{DB_NAME}}"
+
+echo "Creating database '$DB_NAME'..."
+createdb "$DB_NAME" 2>/dev/null && echo "Database created" || echo "Database already exists (or failed)"
+echo ""
+
+echo "Running migrations..."
+(cd server && npm run migrate:latest)
+echo ""
+
+echo "Seeding admin user..."
+(cd server && npm run console -- --task=seed-admin)
+echo ""
+
+echo "=============="
+echo "Database ready!"
+echo ""

package/template/server/.env.sample

@@ -0,0 +1,40 @@
+# Server — Admin API
+PORT={{API_PORT}}
+NODE_ENV=development
+
+# Server — Site API (optional second API)
+SITE_API_PORT={{SITE_API_PORT}}
+
+# URLs
+DOMAIN=http://localhost:{{ADMIN_UI_PORT}}
+SITE_DOMAIN=http://localhost:{{SITE_PORT}}
+BASE_UI_URL=http://localhost:{{ADMIN_UI_PORT}}
+BASE_API_URL=http://localhost:{{API_PORT}}
+BASE_SITE_API_URL=http://localhost:{{SITE_API_PORT}}
+
+# Database (PostgreSQL)
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME={{DB_NAME}}
+DB_USER=postgres
+DB_PASSWORD=postgres
+
+# Authentication
+JWT_TOKEN_SECRET=your-secret-key-change-this-in-production
+COOKIE_DOMAIN=
+
+# Email
+EMAIL_HOST=smtp.example.com
+EMAIL_PORT=465
+EMAIL_SECURE=true
+EMAIL_USER=your-email@example.com
+EMAIL_PASSWORD=your-email-password
+EMAIL_FROM=noreply@{{DOMAIN}}
+EMAIL_NAME={{PROJECT_NAME}}
+EMAIL_REPLY_TO=suporte@{{DOMAIN}}
+
+# AWS S3
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+S3_BUCKET={{PROJECT_SLUG}}-files

package/template/server/.prettierrc

@@ -0,0 +1,4 @@
+{
+    "tabWidth": 4,
+    "semi": true
+}

package/template/server/apps/api/app.ts

@@ -0,0 +1,42 @@
+import dotenv from 'dotenv';
+dotenv.config();
+
+import express from 'express';
+import cors from 'cors';
+import cookieParser from 'cookie-parser';
+import Context from '#core/context.js';
+import logger from '#core/logger.js';
+import makeRoutes from './routes/index.js';
+import requestLoggerMiddleware from '#shared/middlewares/request-logger.js';
+import errorHandler from '#shared/middlewares/error-handler.js';
+
+const app = express();
+const port = parseInt(process.env.PORT || '{{API_PORT}}', 10);
+
+app.use(cors({
+    origin: process.env.DOMAIN || 'http://localhost:{{ADMIN_UI_PORT}}',
+    credentials: true
+}));
+
+app.use(cookieParser());
+app.use(express.json({ limit: '10mb' }));
+app.use(express.urlencoded({ extended: true }));
+app.use(requestLoggerMiddleware);
+
+// Context injection — fresh Context per request
+app.use((req: express.Request, _res: express.Response, next: express.NextFunction) => {
+    req.context = new Context();
+    next();
+});
+
+// Mount all routes
+makeRoutes(app);
+
+// Error handler (must be last)
+app.use(errorHandler);
+
+app.listen(port, () => {
+    logger.info(`Admin API server running on port ${port}`);
+});
+
+export default app;