# elem-app/spaceport architecture

> Architecture diagram of the GitHub repository elem-app/spaceport, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elem-app/spaceport
- Repository: https://github.com/elem-app/spaceport

## Overview

##### Main Components

a. Core Components:
- Spec Processing System
- Code Generation Engine
- Test Execution Environment
- CLI Interface
- LLM Integration Layer

b. Supporting Components:
- Workspace Management
- Template System
- Extension System
- Resource Management

**┌─ User Interface Layer ─────────────────────┐**
- CLI (spaceport_cli/)                       │
- ┬───────────────────────┘
- ↓
**┌─ Core Processing Layer ───────────────────────────────────────────┐**
- ┌─ Spec Processing ─┐ ┌─ Code Generation ┐ ┌─ Test Execution ─┐  │
- speccer/          │ │ tpyi/            │ │ workspace/       │  │
- ┘ └─────────────────┘  └─────────────────┘   │
- ┘
- ↓
**┌─ Extension Layer ──────────────────────────┐**
- spaceport_simpl/ (Testing Extensions)      │
- ┘
- ↓
**┌─ Infrastructure Layer ────────────────────┐**
- LLM Services | File System | Containers   │
- ┘

##### Specific Implementation Details

a. Spec Processing Pipeline:
**Reference Sources → Feature Specs → Executable Specs → Test Code**

b. Extension System:
- Browser testing
- Container testing
- SQL database testing

c. Workspace Management:
- Project organization
- Environment configuration
- Artifact handling

##### Key Architectural Patterns to Emphasize

- Plugin Architecture (for extensions)
- Pipeline Processing (for spec transformation)
- Template-based Generation
- Resource Abstraction Layer

##### Integration Points

Clear integration points for:
- Anthropic API
- OpenAI API
- Docker
- File System
- Testing Tools

##### Additional Elements

A section showing:
- Configuration flow
- Template management
- Resource handling
- Error handling paths

##### Notes for Implementation

- Keep the main flow clear and centered
- Related components visually
- Use consistent sizing for similar components
- Version/environment indicators
- Clear boundaries between system layers

Remember to include the project's unique aspects:
- LLM integration for spec generation
- Template-based code generation
- Extensible testing framework
- Workspace management system

This will create a comprehensive yet clear representation of Spaceport's architecture that accurately reflects its implementation as shown in the file structure and described in the README.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef cli fill:#9370DB,stroke:#333,stroke-width:2px
    classDef core fill:#4682B4,stroke:#333,stroke-width:2px
    classDef extension fill:#90EE90,stroke:#333,stroke-width:2px
    classDef infra fill:#A9A9A9,stroke:#333,stroke-width:2px
    classDef llm fill:#FFD700,stroke:#333,stroke-width:2px
    classDef template fill:#20B2AA,stroke:#333,stroke-width:2px
    classDef resource fill:#DDA0DD,stroke:#333,stroke-width:2px

    %% User Interface Layer
    subgraph UI
        CLI["CLI Interface"]:::cli
        TestCmd["Test Commands"]:::cli
        WorkspaceCmd["Workspace Commands"]:::cli
    end
    click CLI "https://github.com/elem-app/spaceport/blob/main/spaceport_cli/main.py"
    click TestCmd "https://github.com/elem-app/spaceport/blob/main/spaceport_cli/test.py"
    click WorkspaceCmd "https://github.com/elem-app/spaceport/blob/main/spaceport_cli/workspace.py"

    %% Core Processing Layer
    subgraph CoreProcessing
        %% Spec Processing
        subgraph SpecProcessing
            Arranger["Arranger"]:::core
            Rewriter["Rewriter"]:::core
            Transpiler["Transpiler"]:::core
        end
        click Arranger "https://github.com/elem-app/spaceport/blob/main/spaceport/speccer/arranger.py"
        click Rewriter "https://github.com/elem-app/spaceport/blob/main/spaceport/speccer/rewriter.py"
        click Transpiler "https://github.com/elem-app/spaceport/blob/main/spaceport/speccer/transpiler.py"

        %% Code Generation
        subgraph CodeGen
            Executor["Executor"]:::core
            Resolver["Resolver"]:::core
            ErrorHandler["Error Handler"]:::core
        end
        click Executor "https://github.com/elem-app/spaceport/blob/main/spaceport/tpyi/exec.py"
        click Resolver "https://github.com/elem-app/spaceport/blob/main/spaceport/tpyi/resolver.py"
        click ErrorHandler "https://github.com/elem-app/spaceport/blob/main/spaceport/tpyi/errors.py"

        %% Test Execution
        subgraph TestExec
            WorkspaceMgr["Workspace Manager"]:::core
            Environment["Environment"]:::core
            ArtifactMgr["Artifact Manager"]:::core
        end
        click WorkspaceMgr "https://github.com/elem-app/spaceport/blob/main/spaceport/workspace/workspace.py"
        click Environment "https://github.com/elem-app/spaceport/blob/main/spaceport/workspace/env.py"
        click ArtifactMgr "https://github.com/elem-app/spaceport/blob/main/spaceport/workspace/artifact.py"
    end

    %% Template System
    subgraph TemplateSystem
        TemplateEngine["Template Engine"]:::template
        TemplateFiles["Template Files"]:::template
        TemplateMgr["Template Manager"]:::template
    end
    click TemplateEngine "https://github.com/elem-app/spaceport/tree/main/pylib/tem/"
    click TemplateFiles "https://github.com/elem-app/spaceport/tree/main/spaceport/data/templates/"
    click TemplateMgr "https://github.com/elem-app/spaceport/blob/main/pylib/tem/manager.py"

    %% Extension Layer
    subgraph Extensions
        BrowserTest["Browser Testing"]:::extension
        ContainerTest["Container Testing"]:::extension
        FSTest["File System Testing"]:::extension
    end
    click BrowserTest "https://github.com/elem-app/spaceport/blob/main/spaceport_simpl/browser.py"
    click ContainerTest "https://github.com/elem-app/spaceport/blob/main/spaceport_simpl/container.py"
    click FSTest "https://github.com/elem-app/spaceport/blob/main/spaceport_simpl/fs.py"

    %% Operations Framework
    subgraph Operations
        BrowserOps["Browser Operations"]:::core
        FSOps["File System Operations"]:::core
        GUIOps["GUI Operations"]:::core
    end
    click BrowserOps "https://github.com/elem-app/spaceport/blob/main/spaceport/op/browser.py"
    click FSOps "https://github.com/elem-app/spaceport/blob/main/spaceport/op/fs.py"
    click GUIOps "https://github.com/elem-app/spaceport/blob/main/spaceport/op/gui.py"

    %% Subject Management
    subgraph SubjectMgmt
        Factory["Subject Factory"]:::core
        PackageImpl["Package Implementation"]:::core
    end
    click Factory "https://github.com/elem-app/spaceport/blob/main/spaceport/subject/factory.py"
    click PackageImpl "https://github.com/elem-app/spaceport/blob/main/spaceport/subject/impl_pkg.py"

    %% Infrastructure Layer
    subgraph Infrastructure
        LLMService["LLM Service"]:::llm
        ResourceMgr["Resource Manager"]:::resource
    end
    click LLMService "https://github.com/elem-app/spaceport/blob/main/spaceport/llm.py"
    click ResourceMgr "https://github.com/elem-app/spaceport/blob/main/pylib/resource.py"

    %% Relationships
    CLI --> TestCmd & WorkspaceCmd
    TestCmd --> SpecProcessing
    WorkspaceCmd --> WorkspaceMgr
    SpecProcessing --> CodeGen
    CodeGen --> TestExec
    TestExec --> Extensions
    Extensions --> Operations
    Operations --> Infrastructure
    TemplateSystem --> CodeGen
    SubjectMgmt --> TestExec

    %% Legend
    subgraph Legend
        L1["CLI Components"]:::cli
        L2["Core Components"]:::core
        L3["Extension Components"]:::extension
        L4["Infrastructure"]:::infra
        L5["LLM Services"]:::llm
        L6["Template System"]:::template
        L7["Resource Management"]:::resource
    end
```
