Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
Isabella Villaseñor AI is a governed, territorial, and sovereign cognitive infrastructure anchored in Real del Monte, Hidalgo, Mexico. This project provides a governed agential platform comprising five cognitive modules—ISA, SOPHIA, ORION, ARGUS, and CROWN—orchestrated via a Zero-Trust supervision layer. Sources: README.md:1-5, README.md:58-61
The system operates as a federated cognitive infrastructure designed to assist in research and decision-making while maintaining high standards of auditability and cryptographic verification. Sources: src/data/canonical-docs.ts:10-15
Prerequisites and Environment Setup
Before starting development, you must ensure your environment meets the following technical requirements:
- Node.js: Version
22.0.0or higher (below23.0.0). Sources: package.json:7 - Package Manager:
pnpmversion9.0.0or higher. Sources: package.json:8 - Python: Required for the
authz-runtimePDP sidecar. Sources: README.md:92 - Database: PostgreSQL (Supabase/Neon) is the preferred store for production, though SQLite or in-memory stores can be used locally. Sources: README.md:165, server.ts:167-175
Environment Variables
You must configure a .env file based on .env.example. Key variables include:
DATABASE_URL: Connection string for PostgreSQL.ISABELLA_AUTHZ_RUNTIME_URL: URL for the external Policy Decision Point (PDP).FEATURE_LAB_MODE: Enables experimental Post-Quantum Cryptography (PQC).
Sources: README.md:162-171, scripts/check-env.ts
Core Development Workflow
The project uses a standard development cycle involving type checking, testing, and building.
This diagram represents the standard developer onboarding and verification pipeline. Sources: README.md:139-152, CONTRIBUTING.md:15-28
Essential Commands
| Command | Description |
|---|---|
pnpm install | Installs project dependencies using the lockfile. |
npm run dev | Starts the Express server in development mode using tsx. |
npm run lint | Runs tsc --noEmit to verify TypeScript types. |
npm test | Executes the Vitest test suite. |
npm run verify | Compounded command running lint, test, and build. |
npm run check:env | Validates current environment variables against the required contract. |
| Sources: package.json:12-25, AGENTS.md:20-29 |
Project Architecture
The application is split between a React-based Single Page Application (SPA) and an Express-based backend.
Technical Stack
- Frontend: Vite 6, React 19, Tailwind CSS 4. Sources: AGENTS.md:11, package.json:62-65
- Backend: Express server running on Node.js. Sources: AGENTS.md:12, server.ts:105
- Deployment: Vercel handles the SPA from
dist/and API routes via a serverless handler inapi/[...path].ts. Sources: README.md:90-95
Governance and Security
Every interaction within Isabella follows a canonical cognitive cycle to ensure security and auditability:
The sequence shows the 6-step governed cognitive cycle from perception to audit. Sources: src/data/isabellaBlueprint.ts:12-20, server.ts:390-410
Onboarding for New Developers
If you are new to the codebase, the system provides a "Human-facing API" to help you understand specific modules. You can use the explainToDeveloper function to get simplified descriptions and analogies for various system components. Sources: src/lib/automation/human-interface.ts:182-195
System Analogies
To simplify the complex architecture, the system provides analogies for its core modules:
- A-identity: Like a bouncer at a club door checking IDs.
- C-policy: Like a judge who reviews every request.
- V-telemetry: Like a dashboard showing speed and fuel.
- Z-recovery: Like a paramedic who arrives when something breaks.
Sources: src/lib/automation/human-interface.ts:245-271
Conclusion
Getting started with Isabella requires a strict environment setup and adherence to the Zero-Trust governance framework. Developers must verify all changes using the verify command to ensure type safety, test passing, and successful builds before deployment to Vercel. Sources: README.md:201-205, CONTRIBUTING.md:28-36