# coordipai/web-server architecture

> Architecture diagram of the GitHub repository coordipai/web-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coordipai/web-server
- Repository: https://github.com/coordipai/web-server

## Overview

##### Project type and purpose
- From the file tree and common conventions (routers, services, repositories, schemas, a Dockerfile, pyproject.toml) this is a backend-only REST API service written in Python (likely using FastAPI or a similar framework).
- It provides user authentication (JWT, GitHub OAuth, Redis), issue tracking and rescheduling, project and user management, an AI “agent” module (chain, prompts, tool), plus response handling, logging, tracing, and CI/CD.

##### File structure
- Top‐level:
- src/main.py – application entrypoint (mounts routers, middleware, config).
- src/config – database, logger, middleware, tracing, volume (storage) setup.
- src/auth – authentication layer: GitHub OAuth, JWT generation, Redis session caching.
- src/agent – AI agent orchestration: prompt management, chain of tools, router.
- src/issue & src/issue_rescheduling – issue management and automated rescheduling submodule.
- src/project, src/project_user – project entities and assignments.
- src/user & src/user_repository – user profiles versus external user datastore.
- src/response – unified response schemas, error/success definitions.
- src/stat – statistics aggregation.
- Each feature submodule follows the Router → Service → Repository → (Model/Schema) pattern.
- Infrastructure/configuration via Dockerfile, pre-commit, GitHub Actions (deploy.yml, restart.yml).

##### Key architectural patterns
- Layered architecture:
- HTTP layer (FastAPI routers)
- Application/service layer (business logic)
- Data access layer (repositories)
- Configuration & cross-cutting concerns in config (logging, tracing, middleware).
- External integrations: GitHub OAuth, Redis for session store, relational database.
- CI/CD pipelines as part of the overall system delivery.

##### Components and interactions
a. Main Components:
1. Clients (Web or API consumers)
2. API Gateway / FastAPI application
- Routers (auth, agent, issue, issue_rescheduling, project, project_user, user, user_repository, stat)
- Middleware (CORS, authentication, logging, tracing)
3. Service Layer (domain logic for each feature)
4. Repository Layer (ORM or DB connectors)
5. Persistence: Relational Database (PostgreSQL/MySQL)
6. Cache/Session Store: Redis
7. External Service: GitHub OAuth API
8. CI/CD (GitHub Actions) and Docker host for deployment
9. Logging & Tracing Backend
b. Relationships & Data Flows:
- Client → HTTP → FastAPI Router (e.g., /auth, /issue)
- Router → calls Service → calls Repository → Database
- Auth Router → calls GitHub OAuth API & Redis for session/token storage
- Agent Router → calls AI Chain & Tools internally (no external X)
- All requests pass through middleware (logging, tracing) → traces → tracing backend
- Docker build pushes container → deploy pipeline → hosts service
c. Architectural patterns / principles:
- Separation of concerns (layers, modules)
- Dependency inversion (routers depend on abstract services, services on abstract repositories)
- Single responsibility per module (each folder encapsulates one domain concept)
d. Key technologies:
- FastAPI (or similar) for HTTP
- Pydantic for schemas
- SQLAlchemy or another ORM in repo layer
- Redis (session cache)
- GitHub OAuth
- Docker + GitHub Actions

##### Detailed capturing of essential elements
- Middleware and config modules as cross-cutting or a shared library.
- Agent module separately to show its custom chain/prompt/tool flow if needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Clients (Web/API)"]:::external
    Client -->|HTTP Request| main

    subgraph "Application Layer"
        main["Main Entrypoint\nsrc/main.py"]:::app
        middleware["Middleware\nCORS, Auth, Logging, Tracing\nsrc/config/middleware.py"]:::cross
    end

    main --> middleware

    subgraph "Routers" 
        authRouter["Auth Router"]:::code
        agentRouter["Agent Router"]:::code
        issueRouter["Issue Router"]:::code
        issueResRouter["IssueReschedule Router"]:::code
        projectRouter["Project Router"]:::code
        userRouter["User Router"]:::code
        userRepoRouter["UserRepo Router"]:::code
    end

    middleware --> authRouter
    middleware --> agentRouter
    middleware --> issueRouter
    middleware --> issueResRouter
    middleware --> projectRouter
    middleware --> userRouter
    middleware --> userRepoRouter

    subgraph "Services"
        authService["Auth Service"]:::code
        agentService["Agent Chain/Tool"]:::code
        issueService["Issue Service"]:::code
        issueResService["IssueResch Service"]:::code
        projectService["Project Service"]:::code
        userService["User Service"]:::code
        userRepoService["UserRepo Service"]:::code
        statService["Stat Service"]:::code
    end

    authRouter --> authService
    agentRouter --> agentService
    issueRouter --> issueService
    issueResRouter --> issueResService
    projectRouter --> projectService
    userRouter --> userService
    userRepoRouter --> userRepoService

    subgraph "Repositories & Models"
        authRepo["Auth Utils\nJWT, GitHub, Redis"]:::code
        issueRepo["Issue Repository"]:::code
        issueResRepo["IssueResch Repository"]:::code
        projectRepo["Project Repository"]:::code
        projectUserRepo["ProjectUser Repository"]:::code
        userRepo["User Repository"]:::code
        userExtRepo["UserExt Repository"]:::code
    end

    authService --> authRepo
    issueService --> issueRepo
    issueResService --> issueResRepo
    projectService --> projectRepo
    projectService --> projectUserRepo
    userService --> userRepo
    userRepoService --> userExtRepo

    authRepo -->|DB Queries| Database
    issueRepo -->|DB Queries| Database
    issueResRepo -->|DB Queries| Database
    projectRepo -->|DB Queries| Database
    projectUserRepo -->|DB Queries| Database
    userRepo -->|DB Queries| Database
    userExtRepo -->|DB Queries| Database

    subgraph "External Systems"
        Database["Relational DB\n(Postgres/MySQL)"]:::external
        Redis["Redis Session Store"]:::external
        GitHub["GitHub OAuth API"]:::external
        Tracing["Tracing Backend"]:::external
    end

    authRepo --> Redis
    authService -->|OAuth Calls| GitHub
    middleware -->|Send Traces| Tracing

    subgraph "CI/CD & Deployment"
        actions["GitHub Actions"]:::ci
        docker["Docker Build\nDockerfile"]:::ci
        deploy["Deployment Host"]:::external
    end

    actions -.-> docker
    docker -.-> deploy
    main -->|CI Trigger| actions

    classDef code fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef app fill:#B3FFD6,stroke:#28a745,color:#155724
    classDef external fill:#E2FFE2,stroke:#28a745,color:#155724
    classDef cross fill:#FFE8B3,stroke:#fd7e14,color:#856404
    classDef ci fill:#F0F0F0,stroke:#6f42c1,color:#6f42c1

    click main "https://github.com/coordipai/web-server/blob/main/src/main.py"
    click middleware "https://github.com/coordipai/web-server/blob/main/src/config/middleware.py"
    click authRouter "https://github.com/coordipai/web-server/blob/main/src/auth/router.py"
    click authService "https://github.com/coordipai/web-server/blob/main/src/auth/service.py"
    click authRepo "https://github.com/coordipai/web-server/blob/main/src/auth/util/github.py"
    click authRepo "https://github.com/coordipai/web-server/blob/main/src/auth/util/jwt.py"
    click authRepo "https://github.com/coordipai/web-server/blob/main/src/auth/util/redis.py"
    click agentRouter "https://github.com/coordipai/web-server/blob/main/src/agent/router.py"
    click agentService "https://github.com/coordipai/web-server/blob/main/src/agent/chain.py"
    click agentService "https://github.com/coordipai/web-server/blob/main/src/agent/tool.py"
    click issueRouter "https://github.com/coordipai/web-server/blob/main/src/issue/router.py"
    click issueService "https://github.com/coordipai/web-server/blob/main/src/issue/service.py"
    click issueRepo "https://github.com/coordipai/web-server/blob/main/src/issue/repository.py"
    click issueResRouter "https://github.com/coordipai/web-server/blob/main/src/issue_rescheduling/router.py"
    click issueResService "https://github.com/coordipai/web-server/blob/main/src/issue_rescheduling/service.py"
    click issueResRepo "https://github.com/coordipai/web-server/blob/main/src/issue_rescheduling/repository.py"
    click projectRouter "https://github.com/coordipai/web-server/blob/main/src/project/router.py"
    click projectService "https://github.com/coordipai/web-server/blob/main/src/project/service.py"
    click projectRepo "https://github.com/coordipai/web-server/blob/main/src/project/repository.py"
    click projectUserRepo "https://github.com/coordipai/web-server/blob/main/src/project_user/repository.py"
    click userRouter "https://github.com/coordipai/web-server/blob/main/src/user/router.py"
    click userService "https://github.com/coordipai/web-server/blob/main/src/user/service.py"
    click userRepo "https://github.com/coordipai/web-server/blob/main/src/user/repository.py"
    click userRepo "https://github.com/coordipai/web-server/blob/main/src/user_repository/repository.py"
    click userRepoService "https://github.com/coordipai/web-server/blob/main/src/user_repository/service.py"
    click userExtRepo "https://github.com/coordipai/web-server/blob/main/src/user_repository/models.py"
    click statService "https://github.com/coordipai/web-server/blob/main/src/stat/service.py"
    click docker "https://github.com/coordipai/web-server/tree/main/Dockerfile"
    click actions "https://github.com/coordipai/web-server/blob/main/.github/workflows/deploy.yml"
    click actions "https://github.com/coordipai/web-server/blob/main/.github/workflows/restart.yml"
```
