# melkimahdali/zusantara-core architecture

> Architecture diagram of the GitHub repository melkimahdali/zusantara-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/melkimahdali/zusantara-core
- Repository: https://github.com/melkimahdali/zusantara-core

## Overview

Zusantara is a TypeScript web framework paired with an AI-assisted project-editing CLI and a project generator. Developers can create an app from a template, ask the AI to change a project with approval, then run the framework to serve file-based routes. The runtime also provides security, data, UI, and backend capabilities. Paths for unsampled subsystems are grounded in the repository tree and README; their internal call wiring is not inferred where excerpts do not establish it.

Main entry points: [`packages/zusantara/src/core/runtime.ts`](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/runtime.ts) (Request runtime), [`packages/zusantara/src/cli.ts`](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/cli.ts) (Framework CLI), [`packages/zusantara/src/ai/session.ts`](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/session.ts) (AI session), [`packages/zusantara/src/core/router.ts`](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/router.ts) (File router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Developer entrypoints"]
  node_cli["Framework CLI<br/>[cli.ts]"]
  node_tui["Terminal UI<br/>[app.tsx]"]
  node_repl["Browser REPL<br/>[repl.ts]"]
end

subgraph group_ai["AI assistant"]
  node_session["AI session<br/>[session.ts]"]
  node_agent["AI agent<br/>[agent.ts]"]
  node_providers["Provider chain<br/>[chain.ts]"]
  node_approval["Action approval<br/>[approval.ts]"]
  node_tools["Project tools<br/>[tools.ts]"]
  node_saved_sessions[("Saved conversations<br/>[sessions.ts]")]
end

subgraph group_runtime["Web runtime"]
  node_server["App server<br/>[serve.ts]"]
  node_runtime["Request runtime<br/>[runtime.ts]"]
  node_router["File router<br/>[router.ts]"]
  node_middleware["Middleware<br/>[middleware.ts]"]
  node_security["Security controls<br/>[security.ts]"]
  node_sessions["Web sessions<br/>[session.ts]"]
  node_validation["Input validation<br/>[validation.ts]"]
end

subgraph group_capabilities["App capabilities"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_db["Database integration<br/>[index.ts]"]
  node_ui["UI kit<br/>[index.ts]"]
  node_jobs["Jobs and cron<br/>[jobs.ts]"]
  node_mail["Email delivery<br/>[mail.ts]"]
  node_upload["File uploads<br/>[upload.ts]"]
  node_cache["Cache<br/>[cache.ts]"]
end

subgraph group_creation["Project creation"]
  node_create["Project generator<br/>[index.ts]"]
  node_templates["App templates"]
end

node_developer(("Developer"))
node_ai_service{{"AI providers"}}

node_developer -->|"runs commands"| node_cli
node_developer -->|"creates project"| node_create
node_create -->|"copies template"| node_templates
node_cli -->|"starts AI session"| node_session
node_session -->|"runs tasks"| node_agent
node_session -->|"creates chain"| node_providers
node_providers -->|"requests completions"| node_ai_service
node_session -->|"configures policy"| node_approval
node_agent -->|"uses tools"| node_tools
node_session -->|"loads and saves"| node_saved_sessions
node_cli -->|"presents terminal UI"| node_tui
node_cli -->|"offers interactive REPL"| node_repl
node_cli -->|"starts app"| node_server
node_server -->|"serves requests"| node_runtime
node_runtime -->|"dispatches routes"| node_router
node_router -->|"applies middleware"| node_middleware
node_middleware -->|"enforces protections"| node_security
node_middleware -->|"installs sessions"| node_sessions
node_router -->|"validates inputs"| node_validation
node_runtime -->|"provides auth"| node_auth
node_runtime -->|"integrates database"| node_db
node_runtime -->|"provides components"| node_ui
node_runtime -->|"supports background jobs"| node_jobs
node_runtime -->|"supports email"| node_mail
node_runtime -->|"supports uploads"| node_upload
node_runtime -->|"supports caching"| node_cache

click node_cli "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/cli.ts"
click node_tui "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/tui/app.tsx"
click node_repl "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/repl/repl.ts"
click node_create "https://github.com/melkimahdali/zusantara-core/blob/main/packages/create-zusantara/src/index.ts"
click node_templates "https://github.com/melkimahdali/zusantara-core/tree/main/packages/create-zusantara/templates"
click node_session "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/session.ts"
click node_agent "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/agent.ts"
click node_providers "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/chain.ts"
click node_approval "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/approval.ts"
click node_tools "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/tools.ts"
click node_saved_sessions "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/sessions.ts"
click node_server "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/serve.ts"
click node_runtime "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/runtime.ts"
click node_router "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/router.ts"
click node_middleware "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/middleware.ts"
click node_security "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/security.ts"
click node_sessions "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/session.ts"
click node_validation "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/validation.ts"
click node_auth "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/auth.ts"
click node_db "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/db/index.ts"
click node_ui "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ui/index.ts"
click node_jobs "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/backend/jobs.ts"
click node_mail "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/backend/mail.ts"
click node_upload "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/backend/upload.ts"
click node_cache "https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/backend/cache.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_tui,node_repl toneBlue
class node_session,node_agent,node_providers,node_approval,node_tools,node_saved_sessions toneAmber
class node_server,node_runtime,node_router,node_middleware,node_security,node_sessions,node_validation toneMint
class node_auth,node_db,node_ui,node_jobs,node_mail,node_upload,node_cache toneRose
class node_create,node_templates,node_developer,node_ai_service toneIndigo
```

## Components

### Developer entrypoints

- [Framework CLI](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/cli.ts): `packages/zusantara/src/cli.ts`
- [Terminal UI](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/tui/app.tsx): `packages/zusantara/src/tui/app.tsx`
- [Browser REPL](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/repl/repl.ts): `packages/zusantara/src/repl/repl.ts`

### AI assistant

- [AI session](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/session.ts): `packages/zusantara/src/ai/session.ts`
- [AI agent](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/agent.ts): `packages/zusantara/src/ai/agent.ts`
- [Provider chain](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/chain.ts): `packages/zusantara/src/ai/chain.ts`
- [Action approval](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/approval.ts): `packages/zusantara/src/ai/approval.ts`
- [Project tools](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/tools.ts): `packages/zusantara/src/ai/tools.ts`
- [Saved conversations](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ai/sessions.ts): `packages/zusantara/src/ai/sessions.ts`

### Web runtime

- [App server](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/serve.ts): `packages/zusantara/src/serve.ts`
- [Request runtime](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/runtime.ts): `packages/zusantara/src/core/runtime.ts`
- [File router](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/router.ts): `packages/zusantara/src/core/router.ts`
- [Middleware](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/middleware.ts): `packages/zusantara/src/core/middleware.ts`
- [Security controls](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/security.ts): `packages/zusantara/src/core/security.ts`
- [Web sessions](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/session.ts): `packages/zusantara/src/core/session.ts`
- [Input validation](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/validation.ts): `packages/zusantara/src/core/validation.ts`

### App capabilities

- [Authentication](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/core/auth.ts): `packages/zusantara/src/core/auth.ts`
- [Database integration](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/db/index.ts): `packages/zusantara/src/db/index.ts`
- [UI kit](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/ui/index.ts): `packages/zusantara/src/ui/index.ts`
- [Jobs and cron](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/backend/jobs.ts): `packages/zusantara/src/backend/jobs.ts`
- [Email delivery](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/backend/mail.ts): `packages/zusantara/src/backend/mail.ts`
- [File uploads](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/backend/upload.ts): `packages/zusantara/src/backend/upload.ts`
- [Cache](https://github.com/melkimahdali/zusantara-core/blob/main/packages/zusantara/src/backend/cache.ts): `packages/zusantara/src/backend/cache.ts`

### Project creation

- [Project generator](https://github.com/melkimahdali/zusantara-core/blob/main/packages/create-zusantara/src/index.ts): `packages/create-zusantara/src/index.ts`
- [App templates](https://github.com/melkimahdali/zusantara-core/tree/main/packages/create-zusantara/templates): `packages/create-zusantara/templates`

### Other components

- **Developer**
- **AI providers**

## Connections

- Developer → Framework CLI: runs commands
- Developer → Project generator: creates project
- Project generator → App templates: copies template
- Framework CLI → AI session: starts AI session
- AI session → AI agent: runs tasks
- AI session → Provider chain: creates chain
- Provider chain → AI providers: requests completions
- AI session → Action approval: configures policy
- AI agent → Project tools: uses tools
- AI session → Saved conversations: loads and saves
- Framework CLI → Terminal UI: presents terminal UI
- Framework CLI → Browser REPL: offers interactive REPL
- Framework CLI → App server: starts app
- App server → Request runtime: serves requests
- Request runtime → File router: dispatches routes
- File router → Middleware: applies middleware
- Middleware → Security controls: enforces protections
- Middleware → Web sessions: installs sessions
- File router → Input validation: validates inputs
- Request runtime → Authentication: provides auth
- Request runtime → Database integration: integrates database
- Request runtime → UI kit: provides components
- Request runtime → Jobs and cron: supports background jobs
- Request runtime → Email delivery: supports email
- Request runtime → File uploads: supports uploads
- Request runtime → Cache: supports caching