# feharo/software-foundation architecture

> Architecture diagram of the GitHub repository feharo/software-foundation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/feharo/software-foundation
- Repository: https://github.com/feharo/software-foundation

## Overview

Software Foundation is a Python CLI and reusable SaaS starter for bootstrapping applications or adding engineering standards to existing projects. The main workflows are `init` to choose a backend and generate a starter, and `adopt`/`audit`/`upgrade` to inspect or update standards in an existing project. The graph preserves documented agent guidance and performance practices; implementation detail for the generators and upgrade flow is limited to the indexed references and README, so those links cite only that evidence.

Main entry points: [`scripts/foundation.py`](https://github.com/feharo/software-foundation/blob/main/scripts/foundation.py) (CLI entrypoint), [`scripts/new_saas.py`](https://github.com/feharo/software-foundation/blob/main/scripts/new_saas.py) (SaaS generator), [`blueprints/saas-nextjs-postgres/app/api/tasks/route.ts`](https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-postgres/app/api/tasks/route.ts) (Workspace and task API), [`scripts/upgrade.py`](https://github.com/feharo/software-foundation/blob/main/scripts/upgrade.py) (Catalog upgrade)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_cli_entry["CLI entrypoint<br/>[foundation.py]"]
  node_adoption["Adoption and audit<br/>[foundation.py]"]
  node_init["SaaS generator<br/>[new_saas.py]"]
  node_upgrade["Catalog upgrade<br/>[upgrade.py]"]
end

subgraph group_standards["Standards and guidance"]
  node_performance["Performance catalog<br/>[performance.json]"]
  node_profiles["Stack profiles"]
  node_agent_skills["Agent skills"]
  node_agent_templates["Agent instructions"]
end

subgraph group_starters["SaaS starters"]
  node_postgres_starter["PostgreSQL starter"]
  node_supabase_starter["Supabase starter"]
  node_postgres_auth["Better Auth<br/>[auth.ts]"]
  node_postgres_dashboard["Workspace and tasks"]
  node_postgres_api["Workspace and task API<br/>[route.ts]"]
  node_postgres_db[("PostgreSQL pool<br/>[db.ts]")]
  node_supabase_dashboard["Supabase dashboard<br/>[page.tsx]"]
  node_supabase_client["Supabase client<br/>[supabase.ts]"]
end

node_developer(("Developer"))

node_developer -->|"runs commands"| node_cli_entry
node_cli_entry -->|"dispatches init"| node_init
node_cli_entry -->|"dispatches upgrade"| node_upgrade
node_cli_entry -->|"runs adopt or audit"| node_adoption
node_adoption -->|"selects profile"| node_profiles
node_adoption -->|"checks practices"| node_performance
node_adoption -->|"plans instructions"| node_agent_templates
node_upgrade -->|"updates catalog"| node_performance
node_init -->|"generates PostgreSQL"| node_postgres_starter
node_init -->|"generates Supabase"| node_supabase_starter
node_developer -->|"uses guidance"| node_agent_skills
node_postgres_dashboard -->|"calls API"| node_postgres_api
node_postgres_api -->|"queries database"| node_postgres_db
node_postgres_api -->|"resolves identity"| node_postgres_auth
node_postgres_auth -->|"uses pool"| node_postgres_db
node_supabase_dashboard -->|"uses client"| node_supabase_client

click node_cli_entry "https://github.com/feharo/software-foundation/blob/main/scripts/foundation.py"
click node_adoption "https://github.com/feharo/software-foundation/blob/main/scripts/foundation.py"
click node_init "https://github.com/feharo/software-foundation/blob/main/scripts/new_saas.py"
click node_upgrade "https://github.com/feharo/software-foundation/blob/main/scripts/upgrade.py"
click node_performance "https://github.com/feharo/software-foundation/blob/main/standards/performance.json"
click node_profiles "https://github.com/feharo/software-foundation/tree/main/profiles"
click node_agent_skills "https://github.com/feharo/software-foundation/tree/main/skills"
click node_agent_templates "https://github.com/feharo/software-foundation/tree/main/templates"
click node_postgres_starter "https://github.com/feharo/software-foundation/tree/main/blueprints/saas-nextjs-postgres"
click node_supabase_starter "https://github.com/feharo/software-foundation/tree/main/blueprints/saas-nextjs-supabase"
click node_postgres_auth "https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-postgres/lib/auth.ts"
click node_postgres_dashboard "https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-postgres/app/dashboard/dashboard-client.tsx"
click node_postgres_api "https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-postgres/app/api/tasks/route.ts"
click node_postgres_db "https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-postgres/lib/db.ts"
click node_supabase_dashboard "https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-supabase/app/dashboard/page.tsx"
click node_supabase_client "https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-supabase/lib/supabase.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_entry,node_adoption,node_init,node_upgrade toneBlue
class node_performance,node_profiles,node_agent_skills,node_agent_templates toneAmber
class node_postgres_starter,node_supabase_starter,node_postgres_auth,node_postgres_dashboard,node_postgres_api,node_postgres_db,node_supabase_dashboard,node_supabase_client toneMint
class node_developer toneIndigo
```

## Components

### CLI workflows

- [CLI entrypoint](https://github.com/feharo/software-foundation/blob/main/scripts/foundation.py): `scripts/foundation.py`
- [Adoption and audit](https://github.com/feharo/software-foundation/blob/main/scripts/foundation.py): `scripts/foundation.py`
- [SaaS generator](https://github.com/feharo/software-foundation/blob/main/scripts/new_saas.py): `scripts/new_saas.py`
- [Catalog upgrade](https://github.com/feharo/software-foundation/blob/main/scripts/upgrade.py): `scripts/upgrade.py`

### Standards and guidance

- [Performance catalog](https://github.com/feharo/software-foundation/blob/main/standards/performance.json): `standards/performance.json`
- [Stack profiles](https://github.com/feharo/software-foundation/tree/main/profiles): `profiles`
- [Agent skills](https://github.com/feharo/software-foundation/tree/main/skills): `skills`
- [Agent instructions](https://github.com/feharo/software-foundation/tree/main/templates): `templates`

### SaaS starters

- [PostgreSQL starter](https://github.com/feharo/software-foundation/tree/main/blueprints/saas-nextjs-postgres): `blueprints/saas-nextjs-postgres`
- [Supabase starter](https://github.com/feharo/software-foundation/tree/main/blueprints/saas-nextjs-supabase): `blueprints/saas-nextjs-supabase`
- [Better Auth](https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-postgres/lib/auth.ts): `blueprints/saas-nextjs-postgres/lib/auth.ts`
- [Workspace and tasks](https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-postgres/app/dashboard/dashboard-client.tsx): `blueprints/saas-nextjs-postgres/app/dashboard/dashboard-client.tsx`
- [Workspace and task API](https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-postgres/app/api/tasks/route.ts): `blueprints/saas-nextjs-postgres/app/api/tasks/route.ts`
- [PostgreSQL pool](https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-postgres/lib/db.ts): `blueprints/saas-nextjs-postgres/lib/db.ts`
- [Supabase dashboard](https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-supabase/app/dashboard/page.tsx): `blueprints/saas-nextjs-supabase/app/dashboard/page.tsx`
- [Supabase client](https://github.com/feharo/software-foundation/blob/main/blueprints/saas-nextjs-supabase/lib/supabase.ts): `blueprints/saas-nextjs-supabase/lib/supabase.ts`

### Other components

- **Developer**

## Connections

- Developer → CLI entrypoint: runs commands (evidence: `README.md`)
- CLI entrypoint → SaaS generator: dispatches init (evidence: `scripts/foundation.py`)
- CLI entrypoint → Catalog upgrade: dispatches upgrade (evidence: `scripts/foundation.py`)
- CLI entrypoint → Adoption and audit: runs adopt or audit (evidence: `README.md`)
- Adoption and audit → Stack profiles: selects profile (evidence: `scripts/foundation.py`)
- Adoption and audit → Performance catalog: checks practices (evidence: `README.md`)
- Adoption and audit → Agent instructions: plans instructions (evidence: `scripts/foundation.py`)
- Catalog upgrade → Performance catalog: updates catalog (evidence: `README.md`)
- SaaS generator → PostgreSQL starter: generates PostgreSQL (evidence: `README.md`)
- SaaS generator → Supabase starter: generates Supabase (evidence: `README.md`)
- Developer → Agent skills: uses guidance (evidence: `README.md`)
- Workspace and tasks → Workspace and task API: calls API (evidence: `blueprints/saas-nextjs-postgres/app/dashboard/dashboard-client.tsx`)
- Workspace and task API → PostgreSQL pool: queries database (evidence: `blueprints/saas-nextjs-postgres/app/api/tasks/route.ts`)
- Workspace and task API → Better Auth: resolves identity (evidence: `blueprints/saas-nextjs-postgres/app/api/tasks/route.ts`)
- Better Auth → PostgreSQL pool: uses pool (evidence: `blueprints/saas-nextjs-postgres/lib/auth.ts`)
- Supabase dashboard → Supabase client: uses client (evidence: `blueprints/saas-nextjs-supabase/app/dashboard/page.tsx`)
