Build a Personal AI Assistant – Part 1: Architecture Mindset and Environment Setup

When Lumenly’s design lead asked for a personal assistant that could summarize briefs, the first prototype shipped in a weekend: a single JavaScript file that posted prompts to OpenAI. Two weeks later, logs disappeared, API keys leaked, and no one could trace why the assistant sent a stale summary. This series exists so you never relive that fire drill.

Part 1 emphasizes architecture over hero hacks. The thesis is simple: assistants that last are built on reproducible environments, explicit configuration, structured logging, and automation. Once those foundations exist, adding conversation logic (Part 2), memory (Part 3), integrations (Part 4), and testing/deployment (Part 5) becomes incremental.

---

Define the Architecture Principles

Before writing code, align on four non-negotiables:

1. Modular boundaries. Separate configuration, services, utilities, interfaces. If everything lives in index.ts, maintenance dies.
2. Async-first mindset. Assistants juggle API calls, file I/O, calendar syncs. Node’s event loop is powerful only if you treat every heavy task as asynchronous.
3. Security-conscious workflows. Secrets stay in .env, linting guards against accidental leaks, and configuration is environment-specific.
4. Observability from day zero. Even early builds should log requests, tokens, and error stacks to disk; otherwise debugging is guesswork.

Draw the high-level map that the next four parts will fill in:

CLI / API Layer
      │
Config Loader ──► Assistant Core ──► Providers (LLM, Memory, Tools)
      │                    │
Logging + Metrics ◄───────┘

Takeaway: Document the shape of the system before you open your editor.

---

Install Node.js and Essential Tooling

Node 18+ is required for fetch-native APIs and top-level await. Choose one installation path and stick with it.

Option A: Direct install

1. Download LTS from nodejs.org.
2. Run installer; check “Add to PATH.”
3. Verify:

node --version  # v18.x or newer
npm --version   # v9.x or newer

Option B: Node Version Manager (nvm)

# macOS/Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts
nvm alias default lts

# Windows (nvm-windows)
nvm install 18.20.2
nvm use 18.20.2

Core packages

npm init -y
npm install typescript ts-node nodemon eslint prettier pino dotenv
npx tsc --init --rootDir src --outDir dist --esModuleInterop --moduleResolution node --resolveJsonModule --module commonjs

Add npm scripts:

"scripts": {
  "dev": "nodemon --watch src --exec ts-node src/index.ts",
  "build": "tsc",
  "start": "node dist/index.js",
  "lint": "eslint \"src/**/*.ts\"",
  "format": "prettier --write \"src/**/*.ts\"",
  "test": "vitest run"
}

Takeaway: Pin Node/npm early so teammates share the same runtime.

---

Create a Project Skeleton You Can Scale

Structure counters chaos. Start with:

personal-assistant/
├─ src/
│  ├─ config/         # environment + schema
│  ├─ core/           # assistant orchestrator
│  ├─ providers/      # LLM, embeddings, calendar APIs
│  ├─ interfaces/     # CLI or HTTP endpoints
│  └─ utils/          # logging, metrics, helpers
├─ tests/
├─ logs/
├─ scripts/
├─ .env.example
├─ tsconfig.json
└─ package.json

Scaffold key files:

mkdir -p src/{config,core,providers,interfaces,utils} tests logs scripts
touch src/index.ts src/core/assistant.ts src/config/settings.ts src/utils/logger.ts

src/index.ts:

import { loadSettings } from "./config/settings";
import { Assistant } from "./core/assistant";
import { logger } from "./utils/logger";

async function bootstrap() {
  const settings = loadSettings();
  const assistant = new Assistant(settings);
  logger.info({ env: settings.env }, "Assistant ready");
}

bootstrap().catch((err) => {
  logger.error({ err }, "Bootstrap failed");
  process.exit(1);
});

Takeaway: Folders communicate intent—future you will thank present you.

---

Centralize Configuration and Secrets

Use zod or envalid to validate environment variables. Example:

npm install zod envalid

src/config/settings.ts:

import { cleanEnv, str, num, bool } from "envalid";
import { config } from "dotenv";

config();

export type Settings = ReturnType<typeof loadSettings>;

export function loadSettings() {
  const env = cleanEnv(process.env, {
    NODE_ENV: str({ choices: ["development", "staging", "production"] }),
    OPENAI_API_KEY: str(),
    LOG_LEVEL: str({ default: "info" }),
    MAX_TOKENS: num({ default: 800 }),
    MOCK_PROVIDERS: bool({ default: true }),
  });
  return {
    env: env.NODE_ENV,
    openAiKey: env.OPENAI_API_KEY,
    logLevel: env.LOG_LEVEL,
    maxTokens: env.MAX_TOKENS,
    mockProviders: env.MOCK_PROVIDERS,
  };
}

.env.example:

NODE_ENV=development
OPENAI_API_KEY=sk-...
LOG_LEVEL=debug
MAX_TOKENS=800
MOCK_PROVIDERS=true

Never commit .env. Add .env to .gitignore and use a secrets manager (1Password CLI, Doppler, Vault) when you deploy.

Takeaway: Validation catches missing keys before runtime.

---

Wire Logging, Metrics, and Health Checks

Logging is not optional. Use pino for structured logs:

// src/utils/logger.ts
import pino from "pino";
import { loadSettings } from "../config/settings";

const settings = loadSettings();
export const logger = pino({
  level: settings.logLevel,
  transport: {
    target: "pino-pretty",
    options: { colorize: true, translateTime: "SYS:standard" },
  },
});

Emit health metrics via a lightweight helper:

// src/utils/metrics.ts
import fs from "node:fs";
import path from "node:path";

const METRICS_FILE = path.join("logs", "metrics.ndjson");

export function recordMetric(name: string, payload: Record<string, unknown>) {
  const entry = { ts: Date.now(), name, ...payload };
  fs.appendFileSync(METRICS_FILE, JSON.stringify(entry) + "\n");
}

Add a smoke test CLI command:

// scripts/healthcheck.ts
import { loadSettings } from "../src/config/settings";
import { logger } from "../src/utils/logger";

const settings = loadSettings();
logger.info({ env: settings.env }, "Environment OK");

Expose via npm run healthcheck (add script). This ensures that CI and ops can validate configuration quickly.

Takeaway: If you can’t see it, you can’t debug it.

---

Set Up Quality Gates

ESLint + Prettier

.eslintrc.cjs:

module.exports = {
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint"],
  extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended", "prettier"],
  root: true,
};

.prettierrc:

{ "singleQuote": true, "trailingComma": "all", "semi": true }

Git hooks (optional but recommended)

npm install --save-dev husky lint-staged
npx husky install

.husky/pre-commit:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npm run lint

Takeaway: Automate format/lint so reviewers focus on logic.

---

Troubleshooting Playbook

Create docs/troubleshooting.md with common issues:

Symptom	Diagnosis	Fix
ts-node: command not found	Global binary missing	Run npm install --save-dev ts-node
dotenv missing KEY	.env not loaded	Ensure config() is called before cleanEnv
EADDRINUSE	Dev server already running	Kill previous npm run dev process or change port
OpenAI 401	Key revoked/typo	Regenerate key, update secrets manager

Encourage teammates to append to the doc. Pair it with a scripts/reset.sh that purges node_modules and rebuilds dependencies when weirdness strikes.

Takeaway: Write down fixes once so no one repeats the same pain.

---

Verification Checklist

1. npm run dev logs “Assistant ready”.
2. npm run lint passes.
3. npm run test (even if empty) exits with code 0.
4. npm run healthcheck confirms .env values.
5. ls logs shows metrics.ndjson.
6. Git status is clean and .env is ignored.

If any step fails, stop and resolve it before proceeding to Part 2. The next tutorial assumes the environment is reliable.

---

Looking Ahead

With a disciplined foundation you now have:

• Node 18+ environment pinned.
• TypeScript project skeleton with modular directories.
• Validated configuration + secrets handling.
• Structured logging and metrics.
• Lint/test tooling wired through npm scripts.
• Troubleshooting runbook.

Part 2 converts this scaffolding into a real assistant loop: conversation manager, OpenAI client, CLI/REST interface, and error recovery patterns. Until then, explore Agent Observability and Ops to see where today’s logs will eventually stream, and consider setting up a lightweight monitoring stack (Grafana Agent + Loki) so you’re ready for production early.

Run npm run dev once more—you now have an environment you can trust.

---