📖 Bornara AI — Project Manual

🏢 What Is This Project?

bornara-hub is the private central monorepo for Bornara AI — a Canadian sole proprietorship run by Mahdi Moradi in Calgary, Alberta. It is the single source of truth for the entire business: documentation, business planning, tax compliance, project data, and the apps that serve it all.

It contains:

• 3 web apps — docs site (live), hub data-entry app (planned), landing page (planned)
• Business docs — plans, CRA/tax guides, revenue models, roadmaps (private, protected by Cloudflare Access)
• YAML data — timesheets, expenses, tasks (human-readable, git-tracked)
• 14 AI agents + 9 prompt templates — for VS Code Copilot Chat
• Automation scripts — doc fixing, task export, project scaffolding, link validation
• Integration configs — Cloudflare, GitHub, Vercel, IONOS (no passwords ever)

Revenue Streams (2026)

📂 Repository Structure

bornara-hub/
├── MANIFEST.yml                   ← AI reads first — map of everything
├── .github/SESSION_CONTEXT.md     ← AI session handoff notes
├── .github/copilot/
│   ├── instructions.md            ← Master AI instructions
│   └── agents/                    ← 14 agent .agent.md files
├── .github/prompts/               ← 9 prompt .prompt.md files
│
├── apps/
│   ├── docs/                      ← Docusaurus site → docs.bornara.com (LIVE)
│   ├── hub/                       ← Data entry app → hub.bornara.com (planned)
│   └── landing/                   ← Landing page → bornara.com (planned)
│
├── data/
│   ├── timesheets/YYYY-MM.yml     ← Time tracking (AI can read/write)
│   ├── expenses/YYYY-MM.yml       ← Expense tracking (AI can read/write)
│   ├── tasks/YYYY-MM.yml          ← Tasks (done tasks = immutable)
│   └── receipts/YYYY/             ← Receipt files
│
├── business/
│   └── reports/                   ← Generated reports (future use)
│
├── integrations/                  ← Service configs (NO passwords)
│   ├── cloudflare.yml
│   ├── vercel.yml
│   ├── github.yml
│   ├── ionos.yml
│   └── microsoft365.yml
│
└── bornara.code-workspace         ← VS Code multi-root workspace file

🖥️ The 3 Apps

1. apps/docs — Docusaurus Documentation Site ✅ Live

Contains all company docs, business plans, CRA guides, project documentation, the task board, and this manual. Protected by Cloudflare Access so sensitive business content stays private.

2. apps/hub — Data Entry App 🔧 Planned

Purpose: Natural language data entry for timesheets, expenses, and tasks. You type "logged 3 hours on tools research today" → OpenAI parses it → GitHub API writes it as structured YAML to data/. Also shows dashboards: charts, spending summaries, task progress. Replaces manual YAML editing for day-to-day business data.

3. apps/landing — Public Landing Page 🔧 Planned

Purpose: Public company page for visitors and potential clients. Showcases Bornara AI, links to free tools. No sensitive content here.

🌐 Hosting & Domains

Infrastructure Overview

Domain → App Routing

How Cloudflare Access Works

When you visit docs.bornara.com, Cloudflare intercepts the request and asks for your email. It emails a one-time PIN to mahdi@bornara.com. Enter the PIN → you are authenticated for 24 hours. No passwords, no account creation, no app install needed. Team domain: bornara.cloudflareaccess.com

How Cloudflare Pages Auto-Deploy Works

1. You push a commit to main
2. GitHub notifies Cloudflare Pages via webhook
3. Cloudflare runs the build command inside the configured root directory
4. On success, the new version goes live — usually within 1–2 minutes

💻 Running Locally

Prerequisites

• Node.js 18 or higher (LTS recommended)
• npm 9 or higher
• Git
• VS Code + GitHub Copilot extension (for AI agents)

Docs App (apps/docs) — Currently the only app to run

cd apps/docs

npm ci

npm run docs:start

Test the Production Build Locally

cd apps/docs
npm run docs:build   # generates tasks.json + full static build → build/
npm run docs:serve   # serves build/ at http://localhost:3000

Always test the production build locally before pushing if you suspect broken links — Docusaurus build fails on broken internal links.

Landing Page (apps/landing) — Not Built Yet

cd apps/landing
npm ci
npm run dev    # http://localhost:3001

Hub App (apps/hub) — Not Built Yet

cd apps/hub
npm ci
# Create apps/hub/.env.local with:
# OPENAI_API_KEY=sk-...
# GITHUB_TOKEN=ghp-...   (fine-grained, data/ write access only)
npm run dev    # http://localhost:3002

🚀 Deploying

Docs App — Cloudflare Pages Config

The docs app is already connected to Cloudflare Pages. Pushes to main auto-deploy. If you ever need to recreate the project from scratch:

Manual Redeploy (Without Code Change)

Cloudflare Pages → bornara-docs → Deployments → click Retry deployment on the latest build.

Useful when you want to pick up config changes made in the Cloudflare dashboard (e.g., updated build command).

Custom Domain Setup

1. In Cloudflare Pages project, click Custom domains → Add
2. Enter docs.bornara.com
3. Since DNS is already managed by Cloudflare, it connects automatically
4. Then add the Cloudflare Access policy on that domain (Zero Trust → Access → Applications)

Adding Landing and Hub Later

Create separate Cloudflare Pages projects (one per app), each pointing to the same repo but with different root directories: apps/landing and apps/hub respectively.

🗄️ Data Layer (YAML)

All business data lives as YAML files in data/. No database needed. Files are human-readable, git-diffable, version-controlled, and the AI can read and write them directly.

File Locations & Format

AI Write Rules

• AI can add new entries to timesheets and expenses
• AI can add tasks and update non-done tasks
• AI cannot edit or delete done tasks
• AI never stores API keys, tokens, or passwords in any file

Manual Data Entry (Until Hub App Is Built)

Edit YAML files directly in VS Code or ask Copilot to add entries in the correct format. The AI understands the schema from existing files.

⚙️ All npm Scripts (docs app)

Run all commands from inside apps/docs/. Use npm run <script>.

Documentation Site

Linting & Validation

Task / Issue Management

Project Management

🤖 AI Agents (14)

Agents live in .github/copilot/agents/ at the repo root. In VS Code Copilot Chat, type @agent-name to invoke one directly, or just describe your question and Copilot routes to the right agent automatically.

Strategy & Planning

Tax & Compliance

Product & Operations

Code & Documentation

Meta

💬 Prompt Templates (9)

Prompt templates live in .github/prompts/ at the repo root. In VS Code Copilot Chat, type #prompt-name to attach one to your message, or select it with the / menu.

✅ Task Board

The Task Board at /tasks shows all 69 tasks across 8 milestones with filters, progress bars, and checkboxes that persist in your browser.

How It Works

1. npm run docs:build calls issues:export first, which runs scripts/generate-github-issues.js --export-json static/tasks.json
2. The React page fetches /tasks.json on load and renders the board with milestone grouping and person/priority filters
3. Checkbox state is saved to localStorage key bornara-task-done — survives page refresh, but not clearing browser data or switching devices

How to Add or Edit Tasks

1. Open apps/docs/scripts/generate-github-issues.js
2. Find the ISSUES array and add/edit entries following the existing structure
3. Run npm run issues:export to regenerate static/tasks.json
4. Dev server hot-reloads automatically, or run npm run docs:build for a full production rebuild

📁 Docs Folder Structure

All documentation lives under apps/docs/docs/. The Docusaurus sidebar auto-generates from this folder structure — no manual sidebar config needed.

📏 Documentation Standards

Every .md file in docs/ must have this front-matter at the top:

# Document Title

**Owner:** Mahdi Moradi
**Status:** Draft
**Version:** 0.1.0
**Last Updated:** 2026-04-23
**Applies To:** Bornara AI

Auto-Fix Behaviour

🗂️ Project Management Scripts

Scaffold a New Project

cd apps/docs
npm run project:create -- --name "My Project" --id "my-project"

Creates under docs/05_Projects/my-project/: project.json, README.md, and 5 section folders with templates (Overview, Architecture, Data, Platform Services, Operations).

List All Projects

npm run project:list

Prints all projects grouped by status (Active, Planned, On-Hold, Completed) with color coding.

Regenerate Project Registry

npm run registry:update

Scans all project.json files and rewrites docs/01_Portfolio_Management/project-registry.md with tables grouped by status.

🌿 Git Workflow

Typical Workflow

# Make changes to docs, data, or code
git add -A
git commit -m "docs: update april action plan"
git push
# Cloudflare Pages auto-deploys in ~1-2 minutes

Commit Message Convention

❓ FAQ

Why isn't tasks.json committed to the repo?

It's generated at build time from scripts/generate-github-issues.js and gitignored to keep the git history clean. Every build regenerates it fresh from the task definitions in the script.

Why Cloudflare Pages instead of Vercel?

Vercel's free Hobby plan does not support private GitHub organization repos. Since the repo is under the Bornara-AI org, Vercel requires a Pro plan ($20/mo). Cloudflare Pages supports private org repos for free.

Why are business docs inside the docs site instead of a separate private repo?

Originally they were in a separate public repo — a public repo can't hold sensitive data. Now the entire hub is private + protected by Cloudflare Access, so there's no need to separate them. Keeping everything in one place makes it easy for the AI to cross-reference business plans with code decisions.

Why YAML instead of a database?

YAML in git is sufficient for a solo founder. It's human-readable, version-controlled, fully diffable, and the AI can read and write it directly without an API layer. A database adds cost and complexity with no benefit at this scale. Revisit when the hub app needs real-time multi-user features.

How do I add a new documentation page?

Create a .md file in the right subfolder under apps/docs/docs/ with the required front-matter. The sidebar auto-updates on the next build.

How do I add a new standalone React page?

Create a .tsx file in apps/docs/src/pages/. It becomes accessible at /filename automatically.

How do I change the navbar or footer?

Edit apps/docs/docusaurus.config.js — the themeConfig.navbar and themeConfig.footer sections. Push to main and Cloudflare auto-deploys.

Where are all the passwords?

Bitwarden (free cloud). Never in this repo. The integrations/ folder contains only non-secret config: account emails, team names, domain names.

How do I start a new AI session and pick up where things left off?

Tell Copilot to read MANIFEST.yml and .github/SESSION_CONTEXT.md first. These are maintained as the project evolves and give the AI full context on current state, pending tasks, and decisions made.

The task board is blank or shows an error — what happened?

The Cloudflare Pages build command is probably set to npx docusaurus build instead of npm run docs:build. Fix it in: Cloudflare Dashboard → Pages → bornara-docs → Settings → Builds & deployments → Build command. Then trigger a new deployment.