Refining steps and adding design/architecture section

pgraverdy commented 2 years ago

In the README, expand each step and add subitems/subsub items (can mark them done or todo). Many are already in the doc. Its fine to postpone some and explain (e.g., in Step 2, move the CI/Github Actions item to a new Step 6 that can be named "CI Setup" and add a subitem note stating that its delayed as not priority, ...)

Then add a design section in the README.md that presents the architecture of the system you re building. This is really fundamental as it conveys what you understand of the task and what you are aiming at.

You can either do one or more sequence diagram (can be written in markdown/mermaid - check Github MD extensions there). You can use this to identify the different components in the app, and how they communicate.

sequenceDiagram
    participant User
    participant Admin
    participant WebApp
    participant DB
    participant AIServer
    User->>WebApp: HTTP image upload
    WebApp->>DB: image storage
    WebApp->>User: OK
    User->>WebApp: HTTP image analysis form submission
    WebApp->>User: OK (async task ID)
    WebApp->>AIServer: REST API ai_process
    AIServer->>DB : images request
    DB->>AIServer : images
    loop AI Task
        AIServer->>AIServer: Image Processing
    end
    Admin->>WebApp: HTTP server status
    WebApp->>Admin: OK

Alternatively (or in addition), you can make an architecture diagram of the app (wich identifies the "components" that send data, requests, ... and use arrows beteen these components to represent the relationships between the components, the flow of actions/information.

@azlaanmsamad do not hesitate tp ask questions below in the issue if this is not clear.

azlaanmsamad commented 2 years ago

@pgraverdy I have changed the readme to better track progress of the task.

azlaanmsamad commented 2 years ago

@pgraverdy I have added the sequence diagram to the readme

azlaanmsamad commented 2 years ago

@pgraverdy Awaiting your response, please let me know what you think

pgraverdy commented 2 years ago

@azlaanmsamad I added some issues, please have a look and reflect on the sequence diagram.

There are no sensors in the sequence diagram, although they are the source of data
no need here to break down the broker into queue/exchange/...
the user is not explicitely mentionned in the doc. Is it in fact the user or the frontend ? (the "user" can only load a url or click a button in the web browser - that is the browser/frontend that sends the http request to the server/backend)

azlaanmsamad commented 2 years ago

@pgraverdy

I have added the sensors in the sequence diagram.
Removed the queues/exchanges and combined them into a single broker.
Yes right, what I mean by the user is the Frontend.

I have updated the readme.md with sequence diagram, please check it when you have time and let me know your comments.

azlaanmsamad / Inria_Task

Refining steps and adding design/architecture section #3